Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
RHist.hxx
Go to the documentation of this file.
1/// \file
2/// \warning This is part of the %ROOT 7 prototype! It will change without notice. It might trigger earthquakes.
3/// Feedback is welcome!
4
5#ifndef ROOT_RHist
6#define ROOT_RHist
7
8#include "RBinIndex.hxx"
9#include "RHistEngine.hxx"
10#include "RHistStats.hxx"
11#include "RWeight.hxx"
12
13#include <array>
14#include <cassert>
15#include <stdexcept>
16#include <tuple>
17#include <utility>
18#include <vector>
19
20class TBuffer;
21
22namespace ROOT {
23namespace Experimental {
24
25/**
26A histogram for aggregation of data along multiple dimensions.
27
28Every call to \ref Fill(const A &... args) "Fill" increments the bin content and is reflected in global statistics:
29\code
30ROOT::Experimental::RHist<int> hist(10, 5, 15);
31hist.Fill(8.5);
32// hist.GetBinContent(ROOT::Experimental::RBinIndex(3)) will return 1
33\endcode
34
35The class is templated on the bin content type. For counting, as in the example above, it may be an integer type such as
36`int` or `long`. Narrower types such as `unsigned char` or `short` are supported, but may overflow due to their limited
37range and must be used with care. For weighted filling, the bin content type must be a floating-point type such as
38`float` or `double`, or the special type RBinWithError. Note that `float` has a limited significand precision of 24
39bits.
40
41An object can have arbitrary dimensionality determined at run-time. The axis configuration is passed as a vector of
42RAxisVariant:
43\code
44std::vector<ROOT::Experimental::RAxisVariant> axes;
45axes.push_back(ROOT::Experimental::RRegularAxis(10, 5, 15));
46axes.push_back(ROOT::Experimental::RVariableBinAxis({1, 10, 100, 1000}));
47ROOT::Experimental::RHist<int> hist(axes);
48// hist.GetNDimensions() will return 2
49\endcode
50
51\warning This is part of the %ROOT 7 prototype! It will change without notice. It might trigger earthquakes.
52Feedback is welcome!
53*/
54template <typename BinContentType>
55class RHist final {
56 /// The histogram engine including the bin contents.
58 /// The global histogram statistics.
60
61 /// Private constructor based off an engine.
63
64public:
65 /// Construct a histogram.
66 ///
67 /// \param[in] axes the axis objects, must have size > 0
68 explicit RHist(std::vector<RAxisVariant> axes) : fEngine(std::move(axes)), fStats(fEngine.GetNDimensions()) {}
69
70 /// Construct a one-dimensional histogram engine with a regular axis.
71 ///
72 /// \param[in] nNormalBins the number of normal bins, must be > 0
73 /// \param[in] low the lower end of the axis interval (inclusive)
74 /// \param[in] high the upper end of the axis interval (exclusive), must be > low
75 /// \par See also
76 /// the \ref RRegularAxis::RRegularAxis(std::size_t nNormalBins, double low, double high, bool enableFlowBins)
77 /// "constructor of RRegularAxis"
78 RHist(std::size_t nNormalBins, double low, double high) : RHist({RRegularAxis(nNormalBins, low, high)}) {}
79
80 /// The copy constructor is deleted.
81 ///
82 /// Copying all bin contents can be an expensive operation, depending on the number of bins. If required, users can
83 /// explicitly call Clone().
84 RHist(const RHist<BinContentType> &) = delete;
85 /// Efficiently move construct a histogram.
86 ///
87 /// After this operation, the moved-from object is invalid.
89
90 /// The copy assignment operator is deleted.
91 ///
92 /// Copying all bin contents can be an expensive operation, depending on the number of bins. If required, users can
93 /// explicitly call Clone().
95 /// Efficiently move a histogram.
96 ///
97 /// After this operation, the moved-from object is invalid.
99
100 ~RHist() = default;
101
103 const RHistStats &GetStats() const { return fStats; }
104
105 const std::vector<RAxisVariant> &GetAxes() const { return fEngine.GetAxes(); }
106 std::size_t GetNDimensions() const { return fEngine.GetNDimensions(); }
107 std::size_t GetTotalNBins() const { return fEngine.GetTotalNBins(); }
108
109 std::uint64_t GetNEntries() const { return fStats.GetNEntries(); }
110 /// \copydoc RHistStats::ComputeNEffectiveEntries()
112 /// \copydoc RHistStats::ComputeMean()
113 double ComputeMean(std::size_t dim = 0) const { return fStats.ComputeMean(dim); }
114 /// \copydoc RHistStats::ComputeStdDev()
115 double ComputeStdDev(std::size_t dim = 0) const { return fStats.ComputeStdDev(dim); }
116
117 /// Get the content of a single bin.
118 ///
119 /// \code
120 /// ROOT::Experimental::RHist<int> hist({/* two dimensions */});
121 /// std::array<ROOT::Experimental::RBinIndex, 2> indices = {3, 5};
122 /// int content = hist.GetBinContent(indices);
123 /// \endcode
124 ///
125 /// \note Compared to TH1 conventions, the first normal bin has index 0 and underflow and overflow bins are special
126 /// values. See also the class documentation of RBinIndex.
127 ///
128 /// Throws an exception if the number of indices does not match the axis configuration or the bin is not found.
129 ///
130 /// \param[in] indices the array of indices for each axis
131 /// \return the bin content
132 /// \par See also
133 /// the \ref GetBinContent(const A &... args) const "variadic function template overload" accepting arguments
134 /// directly
135 template <std::size_t N>
136 const BinContentType &GetBinContent(const std::array<RBinIndex, N> &indices) const
137 {
138 return fEngine.GetBinContent(indices);
139 }
140
141 /// Get the content of a single bin.
142 ///
143 /// \code
144 /// ROOT::Experimental::RHist<int> hist({/* two dimensions */});
145 /// int content = hist.GetBinContent(ROOT::Experimental::RBinIndex(3), ROOT::Experimental::RBinIndex(5));
146 /// // ... or construct the RBinIndex arguments implicitly from integers:
147 /// content = hist.GetBinContent(3, 5);
148 /// \endcode
149 ///
150 /// \note Compared to TH1 conventions, the first normal bin has index 0 and underflow and overflow bins are special
151 /// values. See also the class documentation of RBinIndex.
152 ///
153 /// Throws an exception if the number of arguments does not match the axis configuration or the bin is not found.
154 ///
155 /// \param[in] args the arguments for each axis
156 /// \return the bin content
157 /// \par See also
158 /// the \ref GetBinContent(const std::array<RBinIndex, N> &indices) const "function overload" accepting
159 /// `std::array`
160 template <typename... A>
161 const BinContentType &GetBinContent(const A &...args) const
162 {
163 return fEngine.GetBinContent(args...);
164 }
165
166 /// Add all bin contents and statistics of another histogram.
167 ///
168 /// Throws an exception if the axes configurations are not identical.
169 ///
170 /// \param[in] other another histogram
172 {
173 fEngine.Add(other.fEngine);
174 fStats.Add(other.fStats);
175 }
176
177 /// Clear all bin contents and statistics.
178 void Clear()
179 {
180 fEngine.Clear();
181 fStats.Clear();
182 }
183
184 /// Clone this histogram.
185 ///
186 /// Copying all bin contents can be an expensive operation, depending on the number of bins.
187 ///
188 /// \return the cloned object
190 {
192 h.fStats = fStats;
193 return h;
194 }
195
196 /// Fill an entry into the histogram.
197 ///
198 /// \code
199 /// ROOT::Experimental::RHist<int> hist({/* two dimensions */});
200 /// auto args = std::make_tuple(8.5, 10.5);
201 /// hist.Fill(args);
202 /// \endcode
203 ///
204 /// If one of the arguments is outside the corresponding axis and flow bins are disabled, the entry will be silently
205 /// discarded.
206 ///
207 /// Throws an exception if the number of arguments does not match the axis configuration.
208 ///
209 /// \param[in] args the arguments for each axis
210 /// \par See also
211 /// the \ref Fill(const A &... args) "variadic function template overload" accepting arguments directly and the
212 /// \ref Fill(const std::tuple<A...> &args, RWeight weight) "overload for weighted filling"
213 template <typename... A>
214 void Fill(const std::tuple<A...> &args)
215 {
216 fEngine.Fill(args);
217 fStats.Fill(args);
218 }
219
220 /// Fill an entry into the histogram with a weight.
221 ///
222 /// This overload is only available for floating-point bin content types (see
223 /// \ref RHistEngine::SupportsWeightedFilling).
224 ///
225 /// \code
226 /// ROOT::Experimental::RHist<float> hist({/* two dimensions */});
227 /// auto args = std::make_tuple(8.5, 10.5);
228 /// hist.Fill(args, ROOT::Experimental::RWeight(0.8));
229 /// \endcode
230 ///
231 /// If one of the arguments is outside the corresponding axis and flow bins are disabled, the entry will be silently
232 /// discarded.
233 ///
234 /// Throws an exception if the number of arguments does not match the axis configuration.
235 ///
236 /// \param[in] args the arguments for each axis
237 /// \param[in] weight the weight for this entry
238 /// \par See also
239 /// the \ref Fill(const A &... args) "variadic function template overload" accepting arguments directly and the
240 /// \ref Fill(const std::tuple<A...> &args) "overload for unweighted filling"
241 template <typename... A>
242 void Fill(const std::tuple<A...> &args, RWeight weight)
243 {
244 fEngine.Fill(args, weight);
245 fStats.Fill(args, weight);
246 }
247
248 /// Fill an entry into the histogram.
249 ///
250 /// \code
251 /// ROOT::Experimental::RHist<int> hist({/* two dimensions */});
252 /// hist.Fill(8.5, 10.5);
253 /// \endcode
254 ///
255 /// For weighted filling, pass an RWeight as the last argument:
256 /// \code
257 /// ROOT::Experimental::RHist<float> hist({/* two dimensions */});
258 /// hist.Fill(8.5, 10.5, ROOT::Experimental::RWeight(0.8));
259 /// \endcode
260 /// This is only available for floating-point bin content types (see \ref RHistEngine::SupportsWeightedFilling).
261 ///
262 /// If one of the arguments is outside the corresponding axis and flow bins are disabled, the entry will be silently
263 /// discarded.
264 ///
265 /// Throws an exception if the number of arguments does not match the axis configuration.
266 ///
267 /// \param[in] args the arguments for each axis
268 /// \par See also
269 /// the function overloads accepting `std::tuple` \ref Fill(const std::tuple<A...> &args) "for unweighted filling"
270 /// and \ref Fill(const std::tuple<A...> &args, RWeight) "for weighted filling"
271 template <typename... A>
272 void Fill(const A &...args)
273 {
274 fEngine.Fill(args...);
275 fStats.Fill(args...);
276 }
277
278 /// %ROOT Streamer function to throw when trying to store an object of this class.
279 void Streamer(TBuffer &) { throw std::runtime_error("unable to store RHist"); }
280};
281
282} // namespace Experimental
283} // namespace ROOT
284
285#endif
#define h(i)
Definition RSha256.hxx:106
Histogram statistics of unbinned values.
void Add(const RHistStats &other)
Add all entries from another statistics object.
void Clear()
Clear this statistics object.
void Fill(const std::tuple< A... > &args)
Fill an entry into this statistics object.
double ComputeNEffectiveEntries() const
Compute the number of effective entries.
std::uint64_t GetNEntries() const
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.
A histogram for aggregation of data along multiple dimensions.
Definition RHist.hxx:55
RHist(const RHist< BinContentType > &)=delete
The copy constructor is deleted.
RHist(RHist< BinContentType > &&)=default
Efficiently move construct a histogram.
double ComputeMean(std::size_t dim=0) const
Compute the arithmetic mean of unbinned values.
Definition RHist.hxx:113
std::size_t GetNDimensions() const
Definition RHist.hxx:106
RHist< BinContentType > & operator=(RHist< BinContentType > &&)=default
Efficiently move a histogram.
void Fill(const std::tuple< A... > &args)
Fill an entry into the histogram.
Definition RHist.hxx:214
RHistStats fStats
The global histogram statistics.
Definition RHist.hxx:59
void Fill(const std::tuple< A... > &args, RWeight weight)
Fill an entry into the histogram with a weight.
Definition RHist.hxx:242
RHistEngine< BinContentType > fEngine
The histogram engine including the bin contents.
Definition RHist.hxx:57
double ComputeNEffectiveEntries() const
Compute the number of effective entries.
Definition RHist.hxx:111
RHist(std::vector< RAxisVariant > axes)
Construct a histogram.
Definition RHist.hxx:68
const RHistStats & GetStats() const
Definition RHist.hxx:103
const RHistEngine< BinContentType > & GetEngine() const
Definition RHist.hxx:102
RHist(std::size_t nNormalBins, double low, double high)
Construct a one-dimensional histogram engine with a regular axis.
Definition RHist.hxx:78
void Streamer(TBuffer &)
ROOT Streamer function to throw when trying to store an object of this class.
Definition RHist.hxx:279
void Fill(const A &...args)
Fill an entry into the histogram.
Definition RHist.hxx:272
std::size_t GetTotalNBins() const
Definition RHist.hxx:107
double ComputeStdDev(std::size_t dim=0) const
Compute the standard deviation of unbinned values.
Definition RHist.hxx:115
void Add(const RHist< BinContentType > &other)
Add all bin contents and statistics of another histogram.
Definition RHist.hxx:171
const BinContentType & GetBinContent(const std::array< RBinIndex, N > &indices) const
Get the content of a single bin.
Definition RHist.hxx:136
const std::vector< RAxisVariant > & GetAxes() const
Definition RHist.hxx:105
RHist< BinContentType > & operator=(const RHist< BinContentType > &)=delete
The copy assignment operator is deleted.
RHist(RHistEngine< BinContentType > engine)
Private constructor based off an engine.
Definition RHist.hxx:62
const BinContentType & GetBinContent(const A &...args) const
Get the content of a single bin.
Definition RHist.hxx:161
RHist< BinContentType > Clone() const
Clone this histogram.
Definition RHist.hxx:189
void Clear()
Clear all bin contents and statistics.
Definition RHist.hxx:178
std::uint64_t GetNEntries() const
Definition RHist.hxx:109
A regular axis with equidistant bins in the interval .
Buffer base class used for serializing objects.
Definition TBuffer.h:43
A weight for filling histograms.
Definition RWeight.hxx:17