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:
A histogram for aggregation of data along multiple dimensions.
void Fill(const std::tuple< A... > &args)
Fill an entry into the histogram.
The class is templated on the bin content type. For counting, as in the example above, it may be an integral 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 not be an integral type, but 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;
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 65 of file RHist.hxx.
|
| template<typename... Axes> |
| | RHist (const RAxisVariant &axis1, const Axes &...axes) |
| | Construct a histogram.
|
| | RHist (const RHist &)=delete |
| | The copy constructor is deleted.
|
| | RHist (RHist &&)=default |
| | Efficiently move construct a histogram.
|
| | RHist (std::initializer_list< RAxisVariant > axes) |
| | Construct a histogram.
|
| | RHist (std::uint64_t nNormalBins, std::pair< double, double > interval) |
| | Construct a one-dimensional histogram with a regular axis.
|
| | RHist (std::vector< RAxisVariant > axes) |
| | Construct a histogram.
|
| | ~RHist ()=default |
| RHist & | operator= (const RHist &)=delete |
| | The copy assignment operator is deleted.
|
| RHist & | operator= (RHist &&)=default |
| | Efficiently move a histogram.
|
| void | Streamer (TBuffer &) |
| | ROOT Streamer function to throw when trying to store an object of this class.
|
| const RHistEngine< BinContentType > & | 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 BinContentType & | GetBinContent (const std::array< RBinIndex, N > &indices) const |
| | Get the content of a single bin.
|
| const BinContentType & | GetBinContent (const std::vector< RBinIndex > &indices) const |
| | Get the content of a single bin.
|
| template<typename... A> |
| const BinContentType & | 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.
|
| 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.
|
| 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.
|
| template<typename... A> |
| void | Fill (const A &...args) |
| | Fill an entry into the histogram.
|
| void | Add (const RHist &other) |
| | Add all bin contents and statistics of another histogram.
|
| void | AddAtomic (const RHist &other) |
| | Add all bin contents and statistics of another histogram using atomic instructions.
|
| void | Clear () |
| | Clear all bin contents and statistics.
|
| RHist | Clone () const |
| | Clone this histogram.
|
| template<typename U> |
| RHist< U > | Convert () const |
| | Convert this histogram to a different bin content type.
|
| void | Scale (double factor) |
| | Scale all histogram bin contents and statistics.
|
| RHist | Slice (const std::vector< RSliceSpec > &sliceSpecs) const |
| | Slice this histogram with an RSliceSpec per dimension.
|
| template<typename... A> |
| RHist | Slice (const A &...args) const |
| | Slice this histogram with an RSliceSpec per dimension.
|
template<typename BinContentType>
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 170 of file RHist.hxx.
template<typename BinContentType>
template<typename U>
Convert this histogram to a different bin content type.
There is no bounds checking to make sure that the converted values can be represented. Note that it is not possible to convert to RBinWithError since the information about individual weights has been lost since filling.
Converting all bin contents can be an expensive operation, depending on the number of bins.
- Returns
- the converted object
Definition at line 455 of file RHist.hxx.
template<typename BinContentType>
template<typename... A>
Fill an entry into the histogram.
For weighted filling, pass an RWeight as the last argument:
A weight for filling histograms.
This is not available for integral 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, 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 392 of file RHist.hxx.
template<typename BinContentType>
template<typename... A>
Fill an entry into the histogram.
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, 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 variadic function template overload accepting arguments directly and the overload for weighted filling
Definition at line 333 of file RHist.hxx.
template<typename BinContentType>
template<typename... A>
Fill an entry into the histogram with a weight.
This overload is not available for integral bin content types (see RHistEngine::SupportsWeightedFilling).
auto args = std::make_tuple(8.5, 10.5);
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] | 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 361 of file RHist.hxx.
template<typename BinContentType>
template<typename... A>
Slice this histogram with an RSliceSpec per dimension.
With a range, only the specified bins are retained. All other bin contents are transferred to the underflow and overflow bins:
auto sliced = hist.Slice(hist.GetAxes()[0].GetNormalRange(1, 5));
Slicing can also perform operations per dimension, see RSliceSpec. RSliceSpec::ROperationRebin allows to rebin the histogram axis, grouping a number of normal bins into a new one:
Rebin the dimension, grouping a number of original bins into a new one.
RSliceSpec::ROperationSum sums the bin contents along that axis, which allows to project to a lower-dimensional histogram:
RHist Slice(const std::vector< RSliceSpec > &sliceSpecs) const
Slice this histogram with an RSliceSpec per dimension.
Sum bins along this dimension, effectively resulting in a projection.
Specification of a slice operation along one dimension.
Note that it is not allowed to sum along all histogram axes because the return value would be a scalar.
Ranges and operations can be combined. In that case, the range is applied before the operation.
- Warning
- Combining a range and the sum operation drops bin contents, which 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 |
- Returns
- the sliced histogram
- See also
- the function overload accepting std::vector
Definition at line 576 of file RHist.hxx.
template<typename BinContentType>
Slice this histogram with an RSliceSpec per dimension.
With a range, only the specified bins are retained. All other bin contents are transferred to the underflow and overflow bins:
auto sliced = hist.Slice({hist.GetAxes()[0].GetNormalRange(1, 5)});
Slicing can also perform operations per dimension, see RSliceSpec. RSliceSpec::ROperationRebin allows to rebin the histogram axis, grouping a number of normal bins into a new one:
RSliceSpec::ROperationSum sums the bin contents along that axis, which allows to project to a lower-dimensional histogram:
Note that it is not allowed to sum along all histogram axes because the return value would be a scalar.
Ranges and operations can be combined. In that case, the range is applied before the operation.
- Warning
- Combining a range and the sum operation drops bin contents, which will taint the global histogram statistics. Attempting to access its values, for example calling GetNEntries(), will throw exceptions.
- Parameters
-
| [in] | sliceSpecs | the slice specifications for each axis |
- Returns
- the sliced histogram
- See also
- the variadic function template overload accepting arguments directly
Definition at line 512 of file RHist.hxx.
