Logo ROOT  
Reference Guide
RHist.hxx
Go to the documentation of this file.
1/// \file ROOT/RHist.hxx
2/// \ingroup Hist ROOT7
3/// \author Axel Naumann <axel@cern.ch>
4/// \date 2015-03-23
5/// \warning This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback
6/// is welcome!
7
8/*************************************************************************
9 * Copyright (C) 1995-2015, Rene Brun and Fons Rademakers. *
10 * All rights reserved. *
11 * *
12 * For the licensing terms see $ROOTSYS/LICENSE. *
13 * For the list of contributors see $ROOTSYS/README/CREDITS. *
14 *************************************************************************/
15
16#ifndef ROOT7_RHist
17#define ROOT7_RHist
18
19#include "ROOT/RSpan.hxx"
20#include "ROOT/RAxis.hxx"
21#include "ROOT/RHistBinIter.hxx"
22#include "ROOT/RHistImpl.hxx"
23#include "ROOT/RHistData.hxx"
24#include "ROOT/RLogger.hxx"
25#include <initializer_list>
26#include <stdexcept>
27
28namespace ROOT {
29namespace Experimental {
30
31// fwd declare for fwd declare for friend declaration in RHist...
32template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
33class RHist;
34
35// fwd declare for friend declaration in RHist.
36template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
37class RHist<DIMENSIONS, PRECISION, STAT...>
38HistFromImpl(std::unique_ptr<typename RHist<DIMENSIONS, PRECISION, STAT...>::ImplBase_t> pHistImpl);
39
40/**
41 \class RHist
42 Histogram class for histograms with `DIMENSIONS` dimensions, where each
43 bin count is stored by a value of type `PRECISION`. STAT stores statistical
44 data of the entries filled into the histogram (bin content, uncertainties etc).
45
46 A histogram counts occurrences of values or n-dimensional combinations thereof.
47 Contrary to for instance a `RTree`, a histogram combines adjacent values. The
48 resolution of this combination is defined by the axis binning, see e.g.
49 http://www.wikiwand.com/en/Histogram
50 */
51
52template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
53class RHist {
54public:
55 /// The type of the `Detail::RHistImplBase` of this histogram.
56 using ImplBase_t =
58 /// The coordinates type: a `DIMENSIONS`-dimensional `std::array` of `double`.
60 /// The type of weights
62 /// Pointer type to `HistImpl_t::Fill`, for faster access.
64 /// Range.
66
68
69 /// Number of dimensions of the coordinates
70 static constexpr int GetNDim() noexcept { return DIMENSIONS; }
71
72 RHist() = default;
73 RHist(RHist &&) = default;
74 RHist(const RHist &other): fImpl(other.fImpl->Clone()), fFillFunc(other.fFillFunc)
75 {}
76
77 /// Create a histogram from an `array` of axes (`RAxisConfig`s). Example code:
78 ///
79 /// Construct a 1-dimensional histogram that can be filled with `floats`s.
80 /// The axis has 10 bins between 0. and 1. The two outermost sets of curly
81 /// braces are to reach the initialization of the `std::array` elements; the
82 /// inner one is for the initialization of a `RAxisCoordinate`.
83 ///
84 /// RHist<1,float> h1f({{ {10, 0., 1.} }});
85 ///
86 /// Construct a 2-dimensional histogram, with the first axis as before, and
87 /// the second axis having non-uniform ("irregular") binning, where all bin-
88 /// edges are specified. As this is itself an array it must be enclosed by
89 /// double curlies.
90 ///
91 /// RHist<2,int> h2i({{ {10, 0., 1.}, {{-1., 0., 1., 10., 100.}} }});
92 explicit RHist(std::array<RAxisConfig, DIMENSIONS> axes);
93
94 /// Constructor overload taking the histogram title.
95 RHist(std::string_view histTitle, std::array<RAxisConfig, DIMENSIONS> axes);
96
97 /// Constructor overload that's only available for a 1-dimensional histogram.
99 explicit RHist(const RAxisConfig &xaxis): RHist(std::array<RAxisConfig, 1>{{xaxis}})
100 {}
101
102 /// Constructor overload that's only available for a 1-dimensional histogram,
103 /// also passing the histogram title.
105 RHist(std::string_view histTitle, const RAxisConfig &xaxis): RHist(histTitle, std::array<RAxisConfig, 1>{{xaxis}})
106 {}
107
108 /// Constructor overload that's only available for a 2-dimensional histogram.
110 RHist(const RAxisConfig &xaxis, const RAxisConfig &yaxis): RHist(std::array<RAxisConfig, 2>{{xaxis, yaxis}})
111 {}
112
113 /// Constructor overload that's only available for a 2-dimensional histogram,
114 /// also passing the histogram title.
116 RHist(std::string_view histTitle, const RAxisConfig &xaxis, const RAxisConfig &yaxis)
117 : RHist(histTitle, std::array<RAxisConfig, 2>{{xaxis, yaxis}})
118 {}
119
120 /// Constructor overload that's only available for a 3-dimensional histogram.
122 RHist(const RAxisConfig &xaxis, const RAxisConfig &yaxis, const RAxisConfig &zaxis)
123 : RHist(std::array<RAxisConfig, 3>{{xaxis, yaxis, zaxis}})
124 {}
125
126 /// Constructor overload that's only available for a 3-dimensional histogram,
127 /// also passing the histogram title.
129 RHist(std::string_view histTitle, const RAxisConfig &xaxis, const RAxisConfig &yaxis, const RAxisConfig &zaxis)
130 : RHist(histTitle, std::array<RAxisConfig, 3>{{xaxis, yaxis, zaxis}})
131 {}
132
133 /// Access the ImplBase_t this RHist points to.
134 ImplBase_t *GetImpl() const noexcept { return fImpl.get(); }
135
136 /// "Steal" the ImplBase_t this RHist points to.
137 std::unique_ptr<ImplBase_t> TakeImpl() && noexcept { return std::move(fImpl); }
138
139 /// Add `weight` to the bin containing coordinate `x`.
140 void Fill(const CoordArray_t &x, Weight_t weight = (Weight_t)1) noexcept { (fImpl.get()->*fFillFunc)(x, weight); }
141
142 /// For each coordinate in `xN`, add `weightN[i]` to the bin at coordinate
143 /// `xN[i]`. The sizes of `xN` and `weightN` must be the same. This is more
144 /// efficient than many separate calls to `Fill()`.
145 void FillN(const std::span<const CoordArray_t> xN, const std::span<const Weight_t> weightN) noexcept
146 {
147 fImpl->FillN(xN, weightN);
148 }
149
150 /// Convenience overload: `FillN()` with weight 1.
151 void FillN(const std::span<const CoordArray_t> xN) noexcept { fImpl->FillN(xN); }
152
153 /// Get the number of entries this histogram was filled with.
154 int64_t GetEntries() const noexcept { return fImpl->GetStat().GetEntries(); }
155
156 /// Get the content of the bin at `x`.
157 Weight_t GetBinContent(const CoordArray_t &x) const { return fImpl->GetBinContent(x); }
158
159 /// Get the uncertainty on the content of the bin at `x`.
160 double GetBinUncertainty(const CoordArray_t &x) const { return fImpl->GetBinUncertainty(x); }
161
162 const_iterator begin() const { return const_iterator(*fImpl, 1); }
163
164 const_iterator end() const { return const_iterator(*fImpl, fImpl->GetNBinsNoOver() + 1); }
165
166 /// Swap *this and other.
167 ///
168 /// Very efficient; swaps the `fImpl` pointers.
170 {
171 std::swap(fImpl, other.fImpl);
172 std::swap(fFillFunc, other.fFillFunc);
173 }
174
175private:
176 /// The actual histogram implementation.
177 std::unique_ptr<ImplBase_t> fImpl;
178
179 /// Pointer to RHistImpl::Fill() member function.
180 FillFunc_t fFillFunc = nullptr; //!
181
182 friend RHist HistFromImpl<>(std::unique_ptr<ImplBase_t>);
183};
184
185/// RHist with no STAT parameter uses RHistStatContent by default.
186template <int DIMENSIONS, class PRECISION>
187class RHist<DIMENSIONS, PRECISION>: public RHist<DIMENSIONS, PRECISION, RHistStatContent> {
188 using RHist<DIMENSIONS, PRECISION, RHistStatContent>::RHist;
189};
190
191/// Swap two histograms.
192///
193/// Very efficient; swaps the `fImpl` pointers.
194template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
196{
197 a.swap(b);
198};
199
200namespace Internal {
201/**
202 Generate RHist::fImpl from RHist constructor arguments.
203 */
204template <int NDIM, int IDIM, class DATA, class... PROCESSEDAXISCONFIG>
206 /// Select the template argument for the next axis type, and "recurse" into
207 /// RHistImplGen for the next axis.
208 template <RAxisConfig::EKind KIND>
209 std::unique_ptr<Detail::RHistImplBase<DATA>>
210 MakeNextAxis(std::string_view title, const std::array<RAxisConfig, NDIM> &axes,
211 PROCESSEDAXISCONFIG... processedAxisArgs)
212 {
213 using NextAxis_t = typename AxisConfigToType<KIND>::Axis_t;
214 NextAxis_t nextAxis = AxisConfigToType<KIND>()(axes[IDIM]);
215 using HistImpl_t = RHistImplGen<NDIM, IDIM + 1, DATA, PROCESSEDAXISCONFIG..., NextAxis_t>;
216 return HistImpl_t()(title, axes, processedAxisArgs..., nextAxis);
217 }
218
219 /// Make a RHistImpl-derived object reflecting the RAxisConfig array.
220 ///
221 /// Delegate to the appropriate MakeNextAxis instantiation, depending on the
222 /// axis type selected in the RAxisConfig.
223 /// \param title - title of the derived object.
224 /// \param axes - `RAxisConfig` objects describing the axis of the resulting
225 /// RHistImpl.
226 /// \param processedAxisArgs - the RAxisBase-derived axis objects describing the
227 /// axes of the resulting RHistImpl. There are `IDIM` of those; in the end
228 /// (`IDIM` == `GetNDim()`), all `axes` have been converted to
229 /// `processedAxisArgs` and the RHistImpl constructor can be invoked, passing
230 /// the `processedAxisArgs`.
231 std::unique_ptr<Detail::RHistImplBase<DATA>> operator()(std::string_view title,
232 const std::array<RAxisConfig, NDIM> &axes,
233 PROCESSEDAXISCONFIG... processedAxisArgs)
234 {
235 switch (axes[IDIM].GetKind()) {
236 case RAxisConfig::kEquidistant: return MakeNextAxis<RAxisConfig::kEquidistant>(title, axes, processedAxisArgs...);
237 case RAxisConfig::kGrow: return MakeNextAxis<RAxisConfig::kGrow>(title, axes, processedAxisArgs...);
238 case RAxisConfig::kIrregular: return MakeNextAxis<RAxisConfig::kIrregular>(title, axes, processedAxisArgs...);
239 default: R__LOG_ERROR(HistLog()) << "Unhandled axis kind";
240 }
241 return nullptr;
242 }
243};
244
245/// Generate RHist::fImpl from constructor arguments; recursion end.
246template <int NDIM, class DATA, class... PROCESSEDAXISCONFIG>
247/// Create the histogram, now that all axis types and initializer objects are
248/// determined.
249struct RHistImplGen<NDIM, NDIM, DATA, PROCESSEDAXISCONFIG...> {
251 std::unique_ptr<HistImplBase_t>
252 operator()(std::string_view title, const std::array<RAxisConfig, DATA::GetNDim()> &, PROCESSEDAXISCONFIG... axisArgs)
253 {
254 using HistImplt_t = Detail::RHistImpl<DATA, PROCESSEDAXISCONFIG...>;
255 return std::make_unique<HistImplt_t>(title, axisArgs...);
256 }
257};
258} // namespace Internal
259
260template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
261RHist<DIMENSIONS, PRECISION, STAT...>::RHist(std::string_view title, std::array<RAxisConfig, DIMENSIONS> axes)
262 : fImpl{std::move(
263 Internal::RHistImplGen<RHist::GetNDim(), 0,
264 Detail::RHistData<DIMENSIONS, PRECISION, std::vector<PRECISION>, STAT...>>()(
265 title, axes))}
266{
267 fFillFunc = fImpl->GetFillFunc();
268}
269
270template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
271RHist<DIMENSIONS, PRECISION, STAT...>::RHist(std::array<RAxisConfig, DIMENSIONS> axes): RHist("", axes)
272{}
273
274/// Adopt an external, stand-alone RHistImpl. The RHist will take ownership.
275template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
276RHist<DIMENSIONS, PRECISION, STAT...>
278{
279 RHist<DIMENSIONS, PRECISION, STAT...> ret;
280 ret.fFillFunc = pHistImpl->GetFillFunc();
281 std::swap(ret.fImpl, pHistImpl);
282 return ret;
283};
284
285/// \name RHist Typedefs
286///\{ Convenience typedefs (ROOT6-compatible type names)
287
288// Keep them as typedefs, to make sure old-style documentation tools can understand them.
294
300
306///\}
307
308/// Add two histograms.
309///
310/// This operation may currently only be performed if the two histograms have
311/// the same axis configuration, use the same precision, and if `from` records
312/// at least the same statistics as `to` (recording more stats is fine).
313///
314/// Adding histograms with incompatible axis binning will be reported at runtime
315/// with an `std::runtime_error`. Insufficient statistics in the source
316/// histogram will be detected at compile-time and result in a compiler error.
317///
318/// In the future, we may either adopt a more relaxed definition of histogram
319/// addition or provide a mechanism to convert from one histogram type to
320/// another. We currently favor the latter path.
321template <int DIMENSIONS, class PRECISION,
322 template <int D_, class P_> class... STAT_TO,
323 template <int D_, class P_> class... STAT_FROM>
325{
326 // Enforce "same axis configuration" policy.
327 auto& toImpl = *to.GetImpl();
328 const auto& fromImpl = *from.GetImpl();
329 for (int dim = 0; dim < DIMENSIONS; ++dim) {
330 if (!toImpl.GetAxis(dim).HasSameBinningAs(fromImpl.GetAxis(dim))) {
331 throw std::runtime_error("Attempted to add RHists with incompatible axis binning");
332 }
333 }
334
335 // Now that we know that the two axes have the same binning, we can just add
336 // the statistics directly.
337 toImpl.GetStat().Add(fromImpl.GetStat());
338}
339
340} // namespace Experimental
341} // namespace ROOT
342
343#endif
constexpr int PRECISION
Definition: MnPrint.cxx:30
#define R__LOG_ERROR(...)
Definition: RLogger.hxx:362
#define b(i)
Definition: RSha256.hxx:100
int type
Definition: TGX11.cxx:121
Iterates over the bins of a RHist or RHistImpl.
Interface class for RHistImpl.
Definition: RHistImpl.hxx:152
void(RHistImplBase::*)(const CoordArray_t &x, Weight_t w) FillFunc_t
Type of the Fill(x, w) function.
Definition: RHistImpl.hxx:164
Hist::CoordArray_t< DATA::GetNDim()> CoordArray_t
Type of the coordinates.
Definition: RHistImpl.hxx:157
Hist::AxisIterRange_t< DIMENSIONS > AxisIterRange_t
Range type.
Definition: RHistImpl.hxx:79
Objects used to configure the different axis types.
Definition: RAxisConfig.hxx:35
@ kGrow
represents a RAxisGrow
Definition: RAxisConfig.hxx:39
@ kEquidistant
represents a RAxisEquidistant
Definition: RAxisConfig.hxx:38
@ kIrregular
represents a RAxisIrregular
Definition: RAxisConfig.hxx:40
Basic histogram statistics, keeping track of the bin content and the total number of calls to Fill().
Definition: RHistData.hxx:36
Histogram class for histograms with DIMENSIONS dimensions, where each bin count is stored by a value ...
Definition: RHist.hxx:53
ImplBase_t * GetImpl() const noexcept
Access the ImplBase_t this RHist points to.
Definition: RHist.hxx:134
static constexpr int GetNDim() noexcept
Number of dimensions of the coordinates.
Definition: RHist.hxx:70
void FillN(const std::span< const CoordArray_t > xN) noexcept
Convenience overload: FillN() with weight 1.
Definition: RHist.hxx:151
PRECISION Weight_t
The type of weights.
Definition: RHist.hxx:61
Weight_t GetBinContent(const CoordArray_t &x) const
Get the content of the bin at x.
Definition: RHist.hxx:157
int64_t GetEntries() const noexcept
Get the number of entries this histogram was filled with.
Definition: RHist.hxx:154
double GetBinUncertainty(const CoordArray_t &x) const
Get the uncertainty on the content of the bin at x.
Definition: RHist.hxx:160
RHist(std::string_view histTitle, const RAxisConfig &xaxis, const RAxisConfig &yaxis)
Constructor overload that's only available for a 2-dimensional histogram, also passing the histogram ...
Definition: RHist.hxx:116
const_iterator end() const
Definition: RHist.hxx:164
RHist(const RAxisConfig &xaxis, const RAxisConfig &yaxis)
Constructor overload that's only available for a 2-dimensional histogram.
Definition: RHist.hxx:110
typename ImplBase_t::FillFunc_t FillFunc_t
Pointer type to HistImpl_t::Fill, for faster access.
Definition: RHist.hxx:63
RHist(const RAxisConfig &xaxis, const RAxisConfig &yaxis, const RAxisConfig &zaxis)
Constructor overload that's only available for a 3-dimensional histogram.
Definition: RHist.hxx:122
void FillN(const std::span< const CoordArray_t > xN, const std::span< const Weight_t > weightN) noexcept
For each coordinate in xN, add weightN[i] to the bin at coordinate xN[i].
Definition: RHist.hxx:145
typename ImplBase_t::AxisIterRange_t AxisRange_t
Range.
Definition: RHist.hxx:65
void Fill(const CoordArray_t &x, Weight_t weight=(Weight_t) 1) noexcept
Add weight to the bin containing coordinate x.
Definition: RHist.hxx:140
RHist(std::string_view histTitle, std::array< RAxisConfig, DIMENSIONS > axes)
Constructor overload taking the histogram title.
Definition: RHist.hxx:261
Detail::RHistBinIter< ImplBase_t > const_iterator
Definition: RHist.hxx:67
const_iterator begin() const
Definition: RHist.hxx:162
RHist(std::string_view histTitle, const RAxisConfig &xaxis, const RAxisConfig &yaxis, const RAxisConfig &zaxis)
Constructor overload that's only available for a 3-dimensional histogram, also passing the histogram ...
Definition: RHist.hxx:129
void swap(RHist< DIMENSIONS, PRECISION, STAT... > &other) noexcept
Swap *this and other.
Definition: RHist.hxx:169
std::unique_ptr< ImplBase_t > fImpl
The actual histogram implementation.
Definition: RHist.hxx:177
std::unique_ptr< ImplBase_t > TakeImpl() &&noexcept
"Steal" the ImplBase_t this RHist points to.
Definition: RHist.hxx:137
RHist(const RHist &other)
Definition: RHist.hxx:74
RHist(RHist &&)=default
RHist(const RAxisConfig &xaxis)
Constructor overload that's only available for a 1-dimensional histogram.
Definition: RHist.hxx:99
RHist(std::array< RAxisConfig, DIMENSIONS > axes)
Create a histogram from an array of axes (RAxisConfigs).
Definition: RHist.hxx:271
FillFunc_t fFillFunc
Pointer to RHistImpl::Fill() member function.
Definition: RHist.hxx:180
typename ImplBase_t::CoordArray_t CoordArray_t
The coordinates type: a DIMENSIONS-dimensional std::array of double.
Definition: RHist.hxx:59
RHist(std::string_view histTitle, const RAxisConfig &xaxis)
Constructor overload that's only available for a 1-dimensional histogram, also passing the histogram ...
Definition: RHist.hxx:105
Double_t x[n]
Definition: legend1.C:17
basic_string_view< char > string_view
class RHist< DIMENSIONS, PRECISION, STAT... > HistFromImpl(std::unique_ptr< typename RHist< DIMENSIONS, PRECISION, STAT... >::ImplBase_t > pHistImpl)
Adopt an external, stand-alone RHistImpl. The RHist will take ownership.
Definition: RHist.hxx:277
void Add(RHist< DIMENSIONS, PRECISION, STAT_TO... > &to, const RHist< DIMENSIONS, PRECISION, STAT_FROM... > &from)
Add two histograms.
Definition: RHist.hxx:324
RLogChannel & HistLog()
Log channel for Hist diagnostics.
Definition: RAxis.cxx:25
void swap(RHist< DIMENSIONS, PRECISION, STAT... > &a, RHist< DIMENSIONS, PRECISION, STAT... > &b) noexcept
Swap two histograms.
Definition: RHist.hxx:195
tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tb...
Converts a RAxisConfig of whatever kind to the corresponding RAxisBase-derived object.
std::unique_ptr< HistImplBase_t > operator()(std::string_view title, const std::array< RAxisConfig, DATA::GetNDim()> &, PROCESSEDAXISCONFIG... axisArgs)
Definition: RHist.hxx:252
Generate RHist::fImpl from RHist constructor arguments.
Definition: RHist.hxx:205
std::unique_ptr< Detail::RHistImplBase< DATA > > MakeNextAxis(std::string_view title, const std::array< RAxisConfig, NDIM > &axes, PROCESSEDAXISCONFIG... processedAxisArgs)
Select the template argument for the next axis type, and "recurse" into RHistImplGen for the next axi...
Definition: RHist.hxx:210
std::unique_ptr< Detail::RHistImplBase< DATA > > operator()(std::string_view title, const std::array< RAxisConfig, NDIM > &axes, PROCESSEDAXISCONFIG... processedAxisArgs)
Make a RHistImpl-derived object reflecting the RAxisConfig array.
Definition: RHist.hxx:231
auto * a
Definition: textangle.C:12