Logo ROOT  
Reference Guide
RHist.hxx
Go to the documentation of this file.
1/// \file ROOT/RHist.h
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 <initializer_list>
25
26namespace ROOT {
27namespace Experimental {
28
29// fwd declare for fwd declare for friend declaration in RHist...
30template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
31class RHist;
32
33// fwd declare for friend declaration in RHist.
34template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
35class RHist<DIMENSIONS, PRECISION, STAT...>
36HistFromImpl(std::unique_ptr<typename RHist<DIMENSIONS, PRECISION, STAT...>::ImplBase_t> pHistImpl);
37
38/**
39 \class RHist
40 Histogram class for histograms with `DIMENSIONS` dimensions, where each
41 bin count is stored by a value of type `PRECISION`. STAT stores statistical
42 data of the entries filled into the histogram (bin content, uncertainties etc).
43
44 A histogram counts occurrences of values or n-dimensional combinations thereof.
45 Contrary to for instance a `RTree`, a histogram combines adjacent values. The
46 resolution of this combination is defined by the axis binning, see e.g.
47 http://www.wikiwand.com/en/Histogram
48 */
49
50template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
51class RHist {
52public:
53 /// The type of the `Detail::RHistImplBase` of this histogram.
54 using ImplBase_t =
56 /// The coordinates type: a `DIMENSIONS`-dimensional `std::array` of `double`.
58 /// The type of weights
60 /// Pointer type to `HistImpl_t::Fill`, for faster access.
62 /// Range.
64
66
67 /// Number of dimensions of the coordinates
68 static constexpr int GetNDim() noexcept { return DIMENSIONS; }
69
70 RHist() = default;
71 RHist(RHist &&) = default;
72 RHist(const RHist &other): fImpl(other.fImpl->Clone()), fFillFunc(other.fFillFunc)
73 {}
74
75 /// Create a histogram from an `array` of axes (`RAxisConfig`s). Example code:
76 ///
77 /// Construct a 1-dimensional histogram that can be filled with `floats`s.
78 /// The axis has 10 bins between 0. and 1. The two outermost sets of curly
79 /// braces are to reach the initialization of the `std::array` elements; the
80 /// inner one is for the initialization of a `RAxisCoordinate`.
81 ///
82 /// RHist<1,float> h1f({{ {10, 0., 1.} }});
83 ///
84 /// Construct a 2-dimensional histogram, with the first axis as before, and
85 /// the second axis having non-uniform ("irregular") binning, where all bin-
86 /// edges are specified. As this is itself an array it must be enclosed by
87 /// double curlies.
88 ///
89 /// RHist<2,int> h2i({{ {10, 0., 1.}, {{-1., 0., 1., 10., 100.}} }});
90 explicit RHist(std::array<RAxisConfig, DIMENSIONS> axes);
91
92 /// Constructor overload taking the histogram title
93 RHist(std::string_view histTitle, std::array<RAxisConfig, DIMENSIONS> axes);
94
95 /// Constructor overload that's only available for a 1-dimensional histogram.
97 explicit RHist(const RAxisConfig &xaxis): RHist(std::array<RAxisConfig, 1>{{xaxis}})
98 {}
99
100 /// Constructor overload that's only available for a 1-dimensional histogram,
101 /// also passing the histogram title.
103 RHist(std::string_view histTitle, const RAxisConfig &xaxis): RHist(histTitle, std::array<RAxisConfig, 1>{{xaxis}})
104 {}
105
106 /// Constructor overload that's only available for a 2-dimensional histogram.
108 RHist(const RAxisConfig &xaxis, const RAxisConfig &yaxis): RHist(std::array<RAxisConfig, 2>{{xaxis, yaxis}})
109 {}
110
111 /// Constructor overload that's only available for a 2-dimensional histogram,
112 /// also passing the histogram title.
114 RHist(std::string_view histTitle, const RAxisConfig &xaxis, const RAxisConfig &yaxis)
115 : RHist(histTitle, std::array<RAxisConfig, 2>{{xaxis, yaxis}})
116 {}
117
118 /// Constructor overload that's only available for a 3-dimensional histogram.
120 RHist(const RAxisConfig &xaxis, const RAxisConfig &yaxis, const RAxisConfig &zaxis)
121 : RHist(std::array<RAxisConfig, 3>{{xaxis, yaxis, zaxis}})
122 {}
123
124 /// Constructor overload that's only available for a 3-dimensional histogram,
125 /// also passing the histogram title.
127 RHist(std::string_view histTitle, const RAxisConfig &xaxis, const RAxisConfig &yaxis, const RAxisConfig &zaxis)
128 : RHist(histTitle, std::array<RAxisConfig, 3>{{xaxis, yaxis, zaxis}})
129 {}
130
131 /// Access the ImplBase_t this RHist points to.
132 ImplBase_t *GetImpl() const noexcept { return fImpl.get(); }
133
134 /// "Steal" the ImplBase_t this RHist points to.
135 std::unique_ptr<ImplBase_t> TakeImpl() && noexcept { return std::move(fImpl); }
136
137 /// Add `weight` to the bin containing coordinate `x`.
138 void Fill(const CoordArray_t &x, Weight_t weight = (Weight_t)1) noexcept { (fImpl.get()->*fFillFunc)(x, weight); }
139
140 /// For each coordinate in `xN`, add `weightN[i]` to the bin at coordinate
141 /// `xN[i]`. The sizes of `xN` and `weightN` must be the same. This is more
142 /// efficient than many separate calls to `Fill()`.
143 void FillN(const std::span<const CoordArray_t> xN, const std::span<const Weight_t> weightN) noexcept
144 {
145 fImpl->FillN(xN, weightN);
146 }
147
148 /// Convenience overload: `FillN()` with weight 1.
149 void FillN(const std::span<const CoordArray_t> xN) noexcept { fImpl->FillN(xN); }
150
151 /// Get the number of entries this histogram was filled with.
152 int64_t GetEntries() const noexcept { return fImpl->GetStat().GetEntries(); }
153
154 /// Get the content of the bin at `x`.
155 Weight_t GetBinContent(const CoordArray_t &x) const { return fImpl->GetBinContent(x); }
156
157 /// Get the uncertainty on the content of the bin at `x`.
158 double GetBinUncertainty(const CoordArray_t &x) const { return fImpl->GetBinUncertainty(x); }
159
161
162 const_iterator end() const { return const_iterator(*fImpl, fImpl->GetNBins()); }
163
164 /// Swap *this and other.
165 ///
166 /// Very efficient; swaps the `fImpl` pointers.
168 {
169 std::swap(fImpl, other.fImpl);
170 std::swap(fFillFunc, other.fFillFunc);
171 }
172
173private:
174 std::unique_ptr<ImplBase_t> fImpl; ///< The actual histogram implementation
175 FillFunc_t fFillFunc = nullptr; ///<! Pinter to RHistImpl::Fill() member function
176
177 friend RHist HistFromImpl<>(std::unique_ptr<ImplBase_t>);
178};
179
180/// RHist with no STAT parameter uses RHistStatContent by default.
181template <int DIMENSIONS, class PRECISION>
182class RHist<DIMENSIONS, PRECISION>: public RHist<DIMENSIONS, PRECISION, RHistStatContent> {
184};
185
186/// Swap two histograms.
187///
188/// Very efficient; swaps the `fImpl` pointers.
189template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
191{
192 a.swap(b);
193};
194
195namespace Internal {
196/**
197 Generate RHist::fImpl from RHist constructor arguments.
198 */
199template <int NDIM, int IDIM, class DATA, class... PROCESSEDAXISCONFIG>
201 /// Select the template argument for the next axis type, and "recurse" into
202 /// RHistImplGen for the next axis.
203 template <RAxisConfig::EKind KIND>
204 std::unique_ptr<Detail::RHistImplBase<DATA>>
205 MakeNextAxis(std::string_view title, const std::array<RAxisConfig, NDIM> &axes,
206 PROCESSEDAXISCONFIG... processedAxisArgs)
207 {
208 using NextAxis_t = typename AxisConfigToType<KIND>::Axis_t;
209 NextAxis_t nextAxis = AxisConfigToType<KIND>()(axes[IDIM]);
210 using HistImpl_t = RHistImplGen<NDIM, IDIM + 1, DATA, PROCESSEDAXISCONFIG..., NextAxis_t>;
211 return HistImpl_t()(title, axes, processedAxisArgs..., nextAxis);
212 }
213
214 /// Make a RHistImpl-derived object reflecting the RAxisConfig array.
215 ///
216 /// Delegate to the appropriate MakeNextAxis instantiation, depending on the
217 /// axis type selected in the RAxisConfig.
218 /// \param axes - `RAxisConfig` objects describing the axis of the resulting
219 /// RHistImpl.
220 /// \param statConfig - the statConfig parameter to be passed to the RHistImpl
221 /// \param processedAxisArgs - the RAxisBase-derived axis objects describing the
222 /// axes of the resulting RHistImpl. There are `IDIM` of those; in the end
223 /// (`IDIM` == `GetNDim()`), all `axes` have been converted to
224 /// `processedAxisArgs` and the RHistImpl constructor can be invoked, passing
225 /// the `processedAxisArgs`.
226 std::unique_ptr<Detail::RHistImplBase<DATA>> operator()(std::string_view title,
227 const std::array<RAxisConfig, NDIM> &axes,
228 PROCESSEDAXISCONFIG... processedAxisArgs)
229 {
230 switch (axes[IDIM].GetKind()) {
231 case RAxisConfig::kEquidistant: return MakeNextAxis<RAxisConfig::kEquidistant>(title, axes, processedAxisArgs...);
232 case RAxisConfig::kGrow: return MakeNextAxis<RAxisConfig::kGrow>(title, axes, processedAxisArgs...);
233 case RAxisConfig::kIrregular: return MakeNextAxis<RAxisConfig::kIrregular>(title, axes, processedAxisArgs...);
234 default: R__ERROR_HERE("HIST") << "Unhandled axis kind";
235 }
236 return nullptr;
237 }
238};
239
240/// Generate RHist::fImpl from constructor arguments; recursion end.
241template <int NDIM, class DATA, class... PROCESSEDAXISCONFIG>
242/// Create the histogram, now that all axis types and initializer objects are
243/// determined.
244struct RHistImplGen<NDIM, NDIM, DATA, PROCESSEDAXISCONFIG...> {
246 std::unique_ptr<HistImplBase_t>
247 operator()(std::string_view title, const std::array<RAxisConfig, DATA::GetNDim()> &, PROCESSEDAXISCONFIG... axisArgs)
248 {
249 using HistImplt_t = Detail::RHistImpl<DATA, PROCESSEDAXISCONFIG...>;
250 return std::make_unique<HistImplt_t>(title, axisArgs...);
251 }
252};
253} // namespace Internal
254
255template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
256RHist<DIMENSIONS, PRECISION, STAT...>::RHist(std::string_view title, std::array<RAxisConfig, DIMENSIONS> axes)
257 : fImpl{std::move(
258 Internal::RHistImplGen<RHist::GetNDim(), 0,
259 Detail::RHistData<DIMENSIONS, PRECISION, std::vector<PRECISION>, STAT...>>()(
260 title, axes))}
261{
262 fFillFunc = fImpl->GetFillFunc();
263}
264
265template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
266RHist<DIMENSIONS, PRECISION, STAT...>::RHist(std::array<RAxisConfig, DIMENSIONS> axes): RHist("", axes)
267{}
268
269/// Adopt an external, stand-alone RHistImpl. The RHist will take ownership.
270template <int DIMENSIONS, class PRECISION, template <int D_, class P_> class... STAT>
271RHist<DIMENSIONS, PRECISION, STAT...>
273{
274 RHist<DIMENSIONS, PRECISION, STAT...> ret;
275 ret.fFillFunc = pHistImpl->GetFillFunc();
276 std::swap(ret.fImpl, pHistImpl);
277 return ret;
278};
279
280/// \name RHist Typedefs
281///\{ Convenience typedefs (ROOT6-compatible type names)
282
283// Keep them as typedefs, to make sure old-style documentation tools can understand them.
289
295
301///\}
302
303/// Add two histograms. This is the generic, inefficient version for now; it
304/// assumes no matching axes.
305template <int DIMENSIONS, class PRECISION_TO, class PRECISION_FROM,
306 template <int D_, class P_> class... STAT_TO,
307 template <int D_, class P_> class... STAT_FROM>
309{
310 auto toImpl = to.GetImpl();
311 auto fillFuncTo = toImpl->GetFillFunc();
312 using HistFrom_t = RHist<DIMENSIONS, PRECISION_FROM, STAT_FROM...>;
313 using FromCoord_t = typename HistFrom_t::CoordArray_t;
314 using FromWeight_t = typename HistFrom_t::Weight_t;
315 auto add = [fillFuncTo, toImpl](const FromCoord_t &x, FromWeight_t c) {
316 (toImpl->*fillFuncTo)(x, c);
317 // RODO: something nice with the uncertainty - depending on whether `to` cares
318 };
319 from.GetImpl()->ApplyXC(add);
320}
321
322} // namespace Experimental
323} // namespace ROOT
324
325#endif
#define PRECISION
Definition: MnPrint.cxx:26
#define R__ERROR_HERE(GROUP)
Definition: RLogger.hxx:183
#define b(i)
Definition: RSha256.hxx:100
#define c(i)
Definition: RSha256.hxx:101
int type
Definition: TGX11.cxx:120
Iterates over the bins of a RHist or RHistImpl.
Interface class for RHistImpl.
Definition: RHistImpl.hxx:141
virtual void ApplyXC(std::function< void(const CoordArray_t &, Weight_t)>) const =0
Apply a function (lambda) to all bins of the histogram.
void(RHistImplBase::*)(const CoordArray_t &x, Weight_t w) FillFunc_t
Type of the Fill(x, w) function.
Definition: RHistImpl.hxx:151
Hist::CoordArray_t< DATA::GetNDim()> CoordArray_t
Type of the coordinate: a DIMENSIONS-dimensional array of doubles.
Definition: RHistImpl.hxx:146
virtual FillFunc_t GetFillFunc() const =0
Retrieve the pointer to the overridden Fill(x, w) function.
Hist::AxisIterRange_t< DIMENSIONS > AxisIterRange_t
Range type.
Definition: RHistImpl.hxx:75
Objects used to configure the different axis types.
Definition: RAxis.hxx:300
@ kGrow
represents a RAxisGrow
Definition: RAxis.hxx:304
@ kEquidistant
represents a RAxisEquidistant
Definition: RAxis.hxx:303
@ kIrregular
represents a RAxisIrregular
Definition: RAxis.hxx:305
Histogram class for histograms with DIMENSIONS dimensions, where each bin count is stored by a value ...
Definition: RHist.hxx:51
ImplBase_t * GetImpl() const noexcept
Access the ImplBase_t this RHist points to.
Definition: RHist.hxx:132
static constexpr int GetNDim() noexcept
Number of dimensions of the coordinates.
Definition: RHist.hxx:68
void FillN(const std::span< const CoordArray_t > xN) noexcept
Convenience overload: FillN() with weight 1.
Definition: RHist.hxx:149
PRECISION Weight_t
The type of weights.
Definition: RHist.hxx:59
Weight_t GetBinContent(const CoordArray_t &x) const
Get the content of the bin at x.
Definition: RHist.hxx:155
int64_t GetEntries() const noexcept
Get the number of entries this histogram was filled with.
Definition: RHist.hxx:152
double GetBinUncertainty(const CoordArray_t &x) const
Get the uncertainty on the content of the bin at x.
Definition: RHist.hxx:158
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:114
const_iterator end() const
Definition: RHist.hxx:162
RHist(const RAxisConfig &xaxis, const RAxisConfig &yaxis)
Constructor overload that's only available for a 2-dimensional histogram.
Definition: RHist.hxx:108
typename ImplBase_t::FillFunc_t FillFunc_t
Pointer type to HistImpl_t::Fill, for faster access.
Definition: RHist.hxx:61
RHist(const RAxisConfig &xaxis, const RAxisConfig &yaxis, const RAxisConfig &zaxis)
Constructor overload that's only available for a 3-dimensional histogram.
Definition: RHist.hxx:120
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:143
typename ImplBase_t::AxisIterRange_t AxisRange_t
Range.
Definition: RHist.hxx:63
void Fill(const CoordArray_t &x, Weight_t weight=(Weight_t) 1) noexcept
Add weight to the bin containing coordinate x.
Definition: RHist.hxx:138
RHist(std::string_view histTitle, std::array< RAxisConfig, DIMENSIONS > axes)
Constructor overload taking the histogram title.
Definition: RHist.hxx:256
Detail::RHistBinIter< ImplBase_t > const_iterator
Definition: RHist.hxx:65
const_iterator begin() const
Definition: RHist.hxx:160
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:127
void swap(RHist< DIMENSIONS, PRECISION, STAT... > &other) noexcept
Swap *this and other.
Definition: RHist.hxx:167
std::unique_ptr< ImplBase_t > fImpl
The actual histogram implementation.
Definition: RHist.hxx:174
std::unique_ptr< ImplBase_t > TakeImpl() &&noexcept
"Steal" the ImplBase_t this RHist points to.
Definition: RHist.hxx:135
RHist(const RHist &other)
Definition: RHist.hxx:72
RHist(RHist &&)=default
RHist(const RAxisConfig &xaxis)
Constructor overload that's only available for a 1-dimensional histogram.
Definition: RHist.hxx:97
RHist(std::array< RAxisConfig, DIMENSIONS > axes)
Create a histogram from an array of axes (RAxisConfigs).
Definition: RHist.hxx:266
FillFunc_t fFillFunc
! Pinter to RHistImpl::Fill() member function
Definition: RHist.hxx:175
typename ImplBase_t::CoordArray_t CoordArray_t
The coordinates type: a DIMENSIONS-dimensional std::array of double.
Definition: RHist.hxx:57
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:103
Double_t x[n]
Definition: legend1.C:17
basic_string_view< char > string_view
RCoordArray< DIMENSIONS > CoordArray_t
Definition: RHistUtils.hxx:53
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:272
void Add(RHist< DIMENSIONS, PRECISION_TO, STAT_TO... > &to, const RHist< DIMENSIONS, PRECISION_FROM, STAT_FROM... > &from)
Add two histograms.
Definition: RHist.hxx:308
void swap(RHist< DIMENSIONS, PRECISION, STAT... > &a, RHist< DIMENSIONS, PRECISION, STAT... > &b) noexcept
Swap two histograms.
Definition: RHist.hxx:190
VSD Structures.
Definition: StringConv.hxx:21
Converts a RAxisConfig of whatever kind to the corresponding RAxisBase-derived object.
Definition: RAxis.hxx:798
std::unique_ptr< HistImplBase_t > operator()(std::string_view title, const std::array< RAxisConfig, DATA::GetNDim()> &, PROCESSEDAXISCONFIG... axisArgs)
Definition: RHist.hxx:247
Generate RHist::fImpl from RHist constructor arguments.
Definition: RHist.hxx:200
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:205
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:226
auto * a
Definition: textangle.C:12