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 integral type such
36as `int` or `long`. Narrower types such as `unsigned char` or `short` are supported, but may overflow due to their
37limited range and must be used with care. For weighted filling, the bin content type must not be an integral type, but
38a floating-point type such as `float` or `double`, or the special type RBinWithError. Note that `float` has a limited
39significand precision of 24 bits.
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] interval the axis interval (lower end inclusive, upper end exclusive)
74 /// \par See also
75 /// the
76 /// \ref RRegularAxis::RRegularAxis(std::size_t nNormalBins, std::pair<double, double> interval, bool enableFlowBins)
77 /// "constructor of RRegularAxis"
78 RHist(std::size_t nNormalBins, std::pair<double, double> interval) : RHist({RRegularAxis(nNormalBins, interval)}) {}
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, or if an argument cannot be
208 /// converted for the axis type at run-time.
209 ///
210 /// \param[in] args the arguments for each axis
211 /// \par See also
212 /// the \ref Fill(const A &... args) "variadic function template overload" accepting arguments directly and the
213 /// \ref Fill(const std::tuple<A...> &args, RWeight weight) "overload for weighted filling"
214 template <typename... A>
215 void Fill(const std::tuple<A...> &args)
216 {
217 fEngine.Fill(args);
218 fStats.Fill(args);
219 }
220
221 /// Fill an entry into the histogram with a weight.
222 ///
223 /// This overload is not available for integral bin content types (see \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, or if an argument cannot be
235 /// converted for the axis type at run-time.
236 ///
237 /// \param[in] args the arguments for each axis
238 /// \param[in] weight the weight for this entry
239 /// \par See also
240 /// the \ref Fill(const A &... args) "variadic function template overload" accepting arguments directly and the
241 /// \ref Fill(const std::tuple<A...> &args) "overload for unweighted filling"
242 template <typename... A>
243 void Fill(const std::tuple<A...> &args, RWeight weight)
244 {
245 fEngine.Fill(args, weight);
246 fStats.Fill(args, weight);
247 }
248
249 /// Fill an entry into the histogram.
250 ///
251 /// \code
252 /// ROOT::Experimental::RHist<int> hist({/* two dimensions */});
253 /// hist.Fill(8.5, 10.5);
254 /// \endcode
255 ///
256 /// For weighted filling, pass an RWeight as the last argument:
257 /// \code
258 /// ROOT::Experimental::RHist<float> hist({/* two dimensions */});
259 /// hist.Fill(8.5, 10.5, ROOT::Experimental::RWeight(0.8));
260 /// \endcode
261 /// This is not available for integral bin content types (see \ref RHistEngine::SupportsWeightedFilling).
262 ///
263 /// If one of the arguments is outside the corresponding axis and flow bins are disabled, the entry will be silently
264 /// discarded.
265 ///
266 /// Throws an exception if the number of arguments does not match the axis configuration, or if an argument cannot be
267 /// converted for the axis type at run-time.
268 ///
269 /// \param[in] args the arguments for each axis
270 /// \par See also
271 /// the function overloads accepting `std::tuple` \ref Fill(const std::tuple<A...> &args) "for unweighted filling"
272 /// and \ref Fill(const std::tuple<A...> &args, RWeight) "for weighted filling"
273 template <typename... A>
274 void Fill(const A &...args)
275 {
276 fEngine.Fill(args...);
277 fStats.Fill(args...);
278 }
279
280 /// %ROOT Streamer function to throw when trying to store an object of this class.
281 void Streamer(TBuffer &) { throw std::runtime_error("unable to store RHist"); }
282};
283
284} // namespace Experimental
285} // namespace ROOT
286
287#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:215
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:243
RHist(std::size_t nNormalBins, std::pair< double, double > interval)
Construct a one-dimensional histogram engine with a regular axis.
Definition RHist.hxx:78
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
void Streamer(TBuffer &)
ROOT Streamer function to throw when trying to store an object of this class.
Definition RHist.hxx:281
void Fill(const A &...args)
Fill an entry into the histogram.
Definition RHist.hxx:274
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