Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
RInterface.hxx
Go to the documentation of this file.
1// Author: Enrico Guiraud, Danilo Piparo CERN 03/2017
2
3/*************************************************************************
4 * Copyright (C) 1995-2021, Rene Brun and Fons Rademakers. *
5 * All rights reserved. *
6 * *
7 * For the licensing terms see $ROOTSYS/LICENSE. *
8 * For the list of contributors see $ROOTSYS/README/CREDITS. *
9 *************************************************************************/
10
11#ifndef ROOT_RDF_TINTERFACE
12#define ROOT_RDF_TINTERFACE
13
14#include "ROOT/RDataSource.hxx"
20#include "ROOT/RDF/RDefine.hxx"
22#include "ROOT/RDF/RFilter.hxx"
27#include "ROOT/RDF/RRange.hxx"
29#include "ROOT/RDF/Utils.hxx"
32#include "ROOT/RResultPtr.hxx"
34#include <string_view>
35#include "ROOT/RVec.hxx"
36#include "ROOT/TypeTraits.hxx"
37#include "RtypesCore.h" // for ULong64_t
38#include "TDirectory.h"
39#include "TH1.h" // For Histo actions
40#include "TH2.h" // For Histo actions
41#include "TH3.h" // For Histo actions
42#include "THn.h"
43#include "THnSparse.h"
44#include "TProfile.h"
45#include "TProfile2D.h"
46#include "TStatistic.h"
47
48#include "RConfigure.h" // for R__HAS_ROOT7
49#ifdef R__HAS_ROOT7
51#include <ROOT/RHist.hxx>
52#include <ROOT/RHistEngine.hxx>
53#include <ROOT/RProfile.hxx>
54#endif
55
56#include <algorithm>
57#include <cstddef>
58#include <initializer_list>
59#include <iterator> // std::back_insterter
60#include <limits>
61#include <memory>
62#include <set>
63#include <sstream>
64#include <stdexcept>
65#include <string>
66#include <type_traits> // is_same, enable_if
67#include <typeinfo>
68#include <unordered_set>
69#include <utility> // std::index_sequence
70#include <vector>
71#include <any>
72
73class TGraph;
74
75// Windows requires a forward decl of printValue to accept it as a valid friend function in RInterface
76namespace ROOT {
79void EnableImplicitMT(UInt_t numthreads);
80class RDataFrame;
81} // namespace ROOT
82namespace cling {
83std::string printValue(ROOT::RDataFrame *tdf);
84}
85
86namespace ROOT {
87namespace RDF {
90namespace TTraits = ROOT::TypeTraits;
91
92template <typename Proxied>
93class RInterface;
94
95using RNode = RInterface<::ROOT::Detail::RDF::RNodeBase>;
96} // namespace RDF
97
98namespace Internal {
99namespace RDF {
101void ChangeEmptyEntryRange(const ROOT::RDF::RNode &node, std::pair<ULong64_t, ULong64_t> &&newRange);
102void ChangeBeginAndEndEntries(const RNode &node, Long64_t begin, Long64_t end);
104std::vector<std::pair<std::uint64_t, std::uint64_t>> GetDatasetGlobalClusterBoundaries(const RNode &node);
106std::string GetDataSourceLabel(const ROOT::RDF::RNode &node);
107void SetTTreeLifeline(ROOT::RDF::RNode &node, std::any lifeline);
108void LoadCustomValues(ROOT::RDF::RNode &node, const std::vector<std::string> &cols,
109 const std::vector<std::size_t> &vecSizes, float vecPadding, ROOT::RVecF &dest);
110} // namespace RDF
111} // namespace Internal
112
113namespace RDF {
114
115// clang-format off
116/**
117 * \class ROOT::RDF::RInterface
118 * \ingroup dataframe
119 * \brief The public interface to the RDataFrame federation of classes.
120 * \tparam Proxied One of the "node" base types (e.g. RLoopManager, RFilterBase). The user never specifies this type manually.
121 *
122 * The documentation of each method features a one liner illustrating how to use the method, for example showing how
123 * the majority of the template parameters are automatically deduced requiring no or very little effort by the user.
124 */
125// clang-format on
126template <typename Proxied>
131 friend std::string cling::printValue(::ROOT::RDataFrame *tdf); // For a nice printing at the prompt
133
134 template <typename T>
135 friend class RInterface;
136
138 friend void RDFInternal::ChangeEmptyEntryRange(const RNode &node, std::pair<ULong64_t, ULong64_t> &&newRange);
139 friend void RDFInternal::ChangeBeginAndEndEntries(const RNode &node, Long64_t start, Long64_t end);
141 friend std::vector<std::pair<std::uint64_t, std::uint64_t>>
143 friend std::string ROOT::Internal::RDF::GetDataSourceLabel(const RNode &node);
144 friend void ROOT::Internal::RDF::SetTTreeLifeline(ROOT::RDF::RNode &node, std::any lifeline);
145 friend void ROOT::Internal::RDF::LoadCustomValues(ROOT::RDF::RNode &node, const std::vector<std::string> &cols,
146 const std::vector<std::size_t> &vecSizes, float vecPadding,
148
149 std::shared_ptr<Proxied> fProxiedPtr; ///< Smart pointer to the graph node encapsulated by this RInterface.
150
151 void LoadValuesCustom(const ColumnNames_t &columnList, const std::vector<std::size_t> &vecSizes, float vecPadding,
153 {
154 const auto validColumnNames = GetValidatedColumnNames(columnList.size(), columnList);
155
156 auto nColumns = columnList.size();
157 std::vector<const std::type_info *> colTypeIDs;
158 colTypeIDs.reserve(nColumns);
159 for (decltype(nColumns) i{}; i < nColumns; i++) {
160 const auto &colName = validColumnNames[i];
161 const auto colTypeName = ROOT::Internal::RDF::ColumnName2ColumnTypeName(
162 colName, /*tree*/ nullptr, GetDataSource(), fColRegister.GetDefine(colName), /*vector2RVec*/ true);
163 const std::type_info *colTypeID = &ROOT::Internal::RDF::TypeName2TypeID(colTypeName);
164 colTypeIDs.push_back(colTypeID);
165 }
166 // Crucial e.g. if the column names do not correspond to already-available column readers created by the data
167 // source
168 CheckAndFillDSColumns(validColumnNames, colTypeIDs);
169
170 // the values are appended to the caller's buffer, which outlives the event loop run below
171 auto location = std::shared_ptr<ROOT::RVecF>(&dest, [](ROOT::RVecF *) {});
172 auto action = RDFInternal::BuildAction(validColumnNames, colTypeIDs, location, vecSizes, vecPadding, fProxiedPtr,
174 auto resPtr = MakeResultPtr(location, *GetLoopManager(), std::move(action));
175
176 *resPtr;
177 }
178
179public:
180 ////////////////////////////////////////////////////////////////////////////
181 /// \brief Copy-assignment operator for RInterface.
182 RInterface &operator=(const RInterface &) = default;
183
184 ////////////////////////////////////////////////////////////////////////////
185 /// \brief Copy-ctor for RInterface.
186 RInterface(const RInterface &) = default;
187
188 ////////////////////////////////////////////////////////////////////////////
189 /// \brief Move-ctor for RInterface.
190 RInterface(RInterface &&) = default;
191
192 ////////////////////////////////////////////////////////////////////////////
193 /// \brief Move-assignment operator for RInterface.
195
196 ////////////////////////////////////////////////////////////////////////////
197 /// \brief Build a RInterface from a RLoopManager.
198 /// This constructor is only available for RInterface<RLoopManager>.
199 template <typename T = Proxied, typename = std::enable_if_t<std::is_same<T, RLoopManager>::value, int>>
200 RInterface(const std::shared_ptr<RLoopManager> &proxied) : RInterfaceBase(proxied), fProxiedPtr(proxied)
201 {
202 }
203
204 ////////////////////////////////////////////////////////////////////////////
205 /// \brief Cast any RDataFrame node to a common type ROOT::RDF::RNode.
206 /// Different RDataFrame methods return different C++ types. All nodes, however,
207 /// can be cast to this common type at the cost of a small performance penalty.
208 /// This allows, for example, storing RDataFrame nodes in a vector, or passing them
209 /// around via (non-template, C++11) helper functions.
210 /// Example usage:
211 /// ~~~{.cpp}
212 /// // a function that conditionally adds a Range to a RDataFrame node.
213 /// RNode MaybeAddRange(RNode df, bool mustAddRange)
214 /// {
215 /// return mustAddRange ? df.Range(1) : df;
216 /// }
217 /// // use as :
218 /// ROOT::RDataFrame df(10);
219 /// auto maybeRanged = MaybeAddRange(df, true);
220 /// ~~~
221 /// Note that it is not a problem to pass RNode's by value.
222 operator RNode() const
223 {
224 return RNode(std::static_pointer_cast<::ROOT::Detail::RDF::RNodeBase>(fProxiedPtr), *fLoopManager, fColRegister);
225 }
226
227 /// \name Transformations
228 /// These functions transform the columns of the dataframe, such as filtering events or defining columns.
229 /// Transformations can be chained, for example
230 /// ~~~{.cpp}
231 /// auto filtered = rdf.Filter(...).Define(...).Define(...);
232 /// ~~~
233 /// \{
234
235 ////////////////////////////////////////////////////////////////////////////
236 /// \brief Append a filter to the call graph.
237 /// \param[in] f Function, lambda expression, functor class or any other callable object. It must return a `bool`
238 /// signalling whether the event has passed the selection (true) or not (false).
239 /// \param[in] columns Names of the columns/branches in input to the filter function.
240 /// \param[in] name Optional name of this filter. See `Report`.
241 /// \return the filter node of the computation graph.
242 ///
243 /// Append a filter node at the point of the call graph corresponding to the
244 /// object this method is called on.
245 /// The callable `f` should not have side-effects (e.g. modification of an
246 /// external or static variable) to ensure correct results when implicit
247 /// multi-threading is active.
248 ///
249 /// RDataFrame only evaluates filters when necessary: if multiple filters
250 /// are chained one after another, they are executed in order and the first
251 /// one returning false causes the event to be discarded.
252 /// Even if multiple actions or transformations depend on the same filter,
253 /// it is executed once per entry. If its result is requested more than
254 /// once, the cached result is served.
255 ///
256 /// ### Example usage:
257 /// ~~~{.cpp}
258 /// // C++ callable (function, functor class, lambda...) that takes two parameters of the types of "x" and "y"
259 /// auto filtered = df.Filter(myCut, {"x", "y"});
260 ///
261 /// // String: it must contain valid C++ except that column names can be used instead of variable names
262 /// auto filtered = df.Filter("x*y > 0");
263 /// ~~~
264 ///
265 /// \note If the body of the string expression contains an explicit `return` statement (even if it is in a nested
266 /// scope), RDataFrame _will not_ add another one in front of the expression. So this will not work:
267 /// ~~~{.cpp}
268 /// df.Filter("Sum(Map(vec, [](float e) { return e*e > 0.5; }))")
269 /// ~~~
270 /// but instead this will:
271 /// ~~~{.cpp}
272 /// df.Filter("return Sum(Map(vec, [](float e) { return e*e > 0.5; }))")
273 /// ~~~
274 template <typename F, std::enable_if_t<!std::is_convertible<F, std::string>::value, int> = 0>
275 RInterface<RDFDetail::RFilter<F, Proxied>> Filter(F f, const ColumnNames_t &columns = {}, std::string_view name = "")
276 {
277 RDFInternal::CheckFilter(f);
278 using ColTypes_t = typename TTraits::CallableTraits<F>::arg_types;
279 constexpr auto nColumns = ColTypes_t::list_size;
280 const auto validColumnNames = GetValidatedColumnNames(nColumns, columns);
281 CheckAndFillDSColumns(validColumnNames, ColTypes_t());
282
284
285 auto filterPtr = std::make_shared<F_t>(std::move(f), validColumnNames, fProxiedPtr, fColRegister, name);
286 return RInterface<F_t>(std::move(filterPtr), *fLoopManager, fColRegister);
287 }
288
289 ////////////////////////////////////////////////////////////////////////////
290 /// \brief Append a filter to the call graph.
291 /// \param[in] f Function, lambda expression, functor class or any other callable object. It must return a `bool`
292 /// signalling whether the event has passed the selection (true) or not (false).
293 /// \param[in] name Optional name of this filter. See `Report`.
294 /// \return the filter node of the computation graph.
295 ///
296 /// Refer to the first overload of this method for the full documentation.
297 template <typename F, std::enable_if_t<!std::is_convertible<F, std::string>::value, int> = 0>
299 {
300 // The sfinae is there in order to pick up the overloaded method which accepts two strings
301 // rather than this template method.
302 return Filter(f, {}, name);
303 }
304
305 ////////////////////////////////////////////////////////////////////////////
306 /// \brief Append a filter to the call graph.
307 /// \param[in] f Function, lambda expression, functor class or any other callable object. It must return a `bool`
308 /// signalling whether the event has passed the selection (true) or not (false).
309 /// \param[in] columns Names of the columns/branches in input to the filter function.
310 /// \return the filter node of the computation graph.
311 ///
312 /// Refer to the first overload of this method for the full documentation.
313 template <typename F>
314 RInterface<RDFDetail::RFilter<F, Proxied>> Filter(F f, const std::initializer_list<std::string> &columns)
315 {
316 return Filter(f, ColumnNames_t{columns});
317 }
318
319 ////////////////////////////////////////////////////////////////////////////
320 /// \brief Append a filter to the call graph.
321 /// \param[in] expression The filter expression in C++
322 /// \param[in] name Optional name of this filter. See `Report`.
323 /// \return the filter node of the computation graph.
324 ///
325 /// The expression is just-in-time compiled and used to filter entries. It must
326 /// be valid C++ syntax in which variable names are substituted with the names
327 /// of branches/columns.
328 ///
329 /// ### Example usage:
330 /// ~~~{.cpp}
331 /// auto filtered_df = df.Filter("myCollection.size() > 3");
332 /// auto filtered_name_df = df.Filter("myCollection.size() > 3", "Minumum collection size");
333 /// ~~~
334 ///
335 /// \note If the body of the string expression contains an explicit `return` statement (even if it is in a nested
336 /// scope), RDataFrame _will not_ add another one in front of the expression. So this will not work:
337 /// ~~~{.cpp}
338 /// df.Filter("Sum(Map(vec, [](float e) { return e*e > 0.5; }))")
339 /// ~~~
340 /// but instead this will:
341 /// ~~~{.cpp}
342 /// df.Filter("return Sum(Map(vec, [](float e) { return e*e > 0.5; }))")
343 /// ~~~
344 RInterface<RDFDetail::RJittedFilter> Filter(std::string_view expression, std::string_view name = "")
345 {
346 const auto jittedFilter = RDFInternal::BookFilterJit(RDFInternal::UpcastNode(fProxiedPtr), name, expression,
347 fColRegister, nullptr, GetDataSource());
348
349 return RInterface<RDFDetail::RJittedFilter>(std::move(jittedFilter), *fLoopManager, fColRegister);
350 }
351
352 ////////////////////////////////////////////////////////////////////////////
353 /// \brief Discard entries with missing values
354 /// \param[in] column Column name whose entries with missing values should be discarded
355 /// \return The filter node of the computation graph
356 ///
357 /// This operation is useful in case an entry of the dataset is incomplete,
358 /// i.e. if one or more of the columns do not have valid values. If the value
359 /// of the input column is missing for an entry, the entire entry will be
360 /// discarded from the rest of this branch of the computation graph.
361 ///
362 /// Use cases include:
363 /// * When processing multiple files, one or more of them is missing a column
364 /// * In horizontal joining with entry matching, a certain dataset has no
365 /// match for the current entry.
366 ///
367 /// ### Example usage:
368 ///
369 /// \code{.py}
370 /// # Assume a dataset with columns [idx, x] matching another dataset with
371 /// # columns [idx, y]. For idx == 42, the right-hand dataset has no match
372 /// df = ROOT.RDataFrame(dataset)
373 /// df_nomissing = df.FilterAvailable("idx").Define("z", "x + y")
374 /// colz = df_nomissing.Take[int]("z")
375 /// \endcode
376 ///
377 /// \code{.cpp}
378 /// // Assume a dataset with columns [idx, x] matching another dataset with
379 /// // columns [idx, y]. For idx == 42, the right-hand dataset has no match
380 /// ROOT::RDataFrame df{dataset};
381 /// auto df_nomissing = df.FilterAvailable("idx")
382 /// .Define("z", [](int x, int y) { return x + y; }, {"x", "y"});
383 /// auto colz = df_nomissing.Take<int>("z");
384 /// \endcode
385 ///
386 /// \note See FilterMissing() if you want to keep only the entries with
387 /// missing values instead.
389 {
390 const auto columns = ColumnNames_t{column.data()};
391 // For now disable this functionality in case of an empty data source and
392 // the column name was not defined previously.
393 if (ROOT::Internal::RDF::GetDataSourceLabel(*this) == "EmptyDS")
394 throw std::runtime_error("Unknown column: \"" + std::string(column) + "\"");
396 auto filterPtr = std::make_shared<F_t>(/*discardEntry*/ true, fProxiedPtr, fColRegister, columns);
398 return RInterface<F_t>(std::move(filterPtr), *fLoopManager, fColRegister);
399 }
400
401 ////////////////////////////////////////////////////////////////////////////
402 /// \brief Keep only the entries that have missing values.
403 /// \param[in] column Column name whose entries with missing values should be kept
404 /// \return The filter node of the computation graph
405 ///
406 /// This operation is useful in case an entry of the dataset is incomplete,
407 /// i.e. if one or more of the columns do not have valid values. It only
408 /// keeps the entries for which the value of the input column is missing.
409 ///
410 /// Use cases include:
411 /// * When processing multiple files, one or more of them is missing a column
412 /// * In horizontal joining with entry matching, a certain dataset has no
413 /// match for the current entry.
414 ///
415 /// ### Example usage:
416 ///
417 /// \code{.py}
418 /// # Assume a dataset made of two files vertically chained together, one has
419 /// # column "x" and the other has column "y"
420 /// df = ROOT.RDataFrame(dataset)
421 /// df_valid_col_x = df.FilterMissing("y")
422 /// df_valid_col_y = df.FilterMissing("x")
423 /// display_x = df_valid_col_x.Display(("x",))
424 /// display_y = df_valid_col_y.Display(("y",))
425 /// \endcode
426 ///
427 /// \code{.cpp}
428 /// // Assume a dataset made of two files vertically chained together, one has
429 /// // column "x" and the other has column "y"
430 /// ROOT.RDataFrame df{dataset};
431 /// auto df_valid_col_x = df.FilterMissing("y");
432 /// auto df_valid_col_y = df.FilterMissing("x");
433 /// auto display_x = df_valid_col_x.Display<int>({"x"});
434 /// auto display_y = df_valid_col_y.Display<int>({"y"});
435 /// \endcode
436 ///
437 /// \note See FilterAvailable() if you want to discard the entries in case
438 /// there is a missing value instead.
440 {
441 const auto columns = ColumnNames_t{column.data()};
442 // For now disable this functionality in case of an empty data source and
443 // the column name was not defined previously.
444 if (ROOT::Internal::RDF::GetDataSourceLabel(*this) == "EmptyDS")
445 throw std::runtime_error("Unknown column: \"" + std::string(column) + "\"");
447 auto filterPtr = std::make_shared<F_t>(/*discardEntry*/ false, fProxiedPtr, fColRegister, columns);
449 return RInterface<F_t>(std::move(filterPtr), *fLoopManager, fColRegister);
450 }
451
452 // clang-format off
453 ////////////////////////////////////////////////////////////////////////////
454 /// \brief Define a new column.
455 /// \param[in] name The name of the defined column.
456 /// \param[in] expression Function, lambda expression, functor class or any other callable object producing the defined value. Returns the value that will be assigned to the defined column. This callable must be thread safe when used with multiple threads.
457 /// \param[in] columns Names of the columns/branches in input to the producer function.
458 /// \return the first node of the computation graph for which the new quantity is defined.
459 ///
460 /// Define a column that will be visible from all subsequent nodes
461 /// of the functional chain. The `expression` is only evaluated for entries that pass
462 /// all the preceding filters.
463 /// A new variable is created called `name`, accessible as if it was contained
464 /// in the dataset from subsequent transformations/actions.
465 ///
466 /// Use cases include:
467 /// * caching the results of complex calculations for easy and efficient multiple access
468 /// * extraction of quantities of interest from complex objects
469 ///
470 /// An exception is thrown if the name of the new column is already in use in this branch of the computation graph.
471 /// Note that the callable must be thread safe when called from multiple threads. Use DefineSlot() if needed.
472 ///
473 /// ### Example usage:
474 /// ~~~{.cpp}
475 /// // assuming a function with signature:
476 /// double myComplexCalculation(const RVec<float> &muon_pts);
477 /// // we can pass it directly to Define
478 /// auto df_with_define = df.Define("newColumn", myComplexCalculation, {"muon_pts"});
479 /// // alternatively, we can pass the body of the function as a string, as in Filter:
480 /// auto df_with_define = df.Define("newColumn", "x*x + y*y");
481 /// ~~~
482 ///
483 /// \note If the body of the string expression contains an explicit `return` statement (even if it is in a nested
484 /// scope), RDataFrame _will not_ add another one in front of the expression. So this will not work:
485 /// ~~~{.cpp}
486 /// df.Define("x2", "Map(v, [](float e) { return e*e; })")
487 /// ~~~
488 /// but instead this will:
489 /// ~~~{.cpp}
490 /// df.Define("x2", "return Map(v, [](float e) { return e*e; })")
491 /// ~~~
492 template <typename F, typename std::enable_if_t<!std::is_convertible<F, std::string>::value, int> = 0>
493 RInterface<Proxied> Define(std::string_view name, F expression, const ColumnNames_t &columns = {})
494 {
495 return DefineImpl<F, RDFDetail::ExtraArgsForDefine::None>(name, std::move(expression), columns, "Define");
496 }
497 // clang-format on
498
499 // clang-format off
500 ////////////////////////////////////////////////////////////////////////////
501 /// \brief Define a new column with a value dependent on the processing slot.
502 /// \param[in] name The name of the defined column.
503 /// \param[in] expression Function, lambda expression, functor class or any other callable object producing the defined value. Returns the value that will be assigned to the defined column.
504 /// \param[in] columns Names of the columns/branches in input to the producer function (excluding the slot number).
505 /// \return the first node of the computation graph for which the new quantity is defined.
506 ///
507 /// This alternative implementation of `Define` is meant as a helper to evaluate new column values in a thread-safe manner.
508 /// The expression must be a callable of signature R(unsigned int, T1, T2, ...) where `T1, T2...` are the types
509 /// of the columns that the expression takes as input. The first parameter is reserved for an unsigned integer
510 /// representing a "slot number". RDataFrame guarantees that different threads will invoke the expression with
511 /// different slot numbers - slot numbers will range from zero to ROOT::GetThreadPoolSize()-1.
512 /// Note that there is no guarantee as to how often each slot will be reached during the event loop.
513 ///
514 /// The following two calls are equivalent, although `DefineSlot` is slightly more performant:
515 /// ~~~{.cpp}
516 /// int function(unsigned int, double, double);
517 /// df.Define("x", function, {"rdfslot_", "column1", "column2"})
518 /// df.DefineSlot("x", function, {"column1", "column2"})
519 /// ~~~
520 ///
521 /// See Define() for more information.
522 template <typename F>
523 RInterface<Proxied> DefineSlot(std::string_view name, F expression, const ColumnNames_t &columns = {})
524 {
525 return DefineImpl<F, RDFDetail::ExtraArgsForDefine::Slot>(name, std::move(expression), columns, "DefineSlot");
526 }
527 // clang-format on
528
529 // clang-format off
530 ////////////////////////////////////////////////////////////////////////////
531 /// \brief Define a new column with a value dependent on the processing slot and the current entry.
532 /// \param[in] name The name of the defined column.
533 /// \param[in] expression Function, lambda expression, functor class or any other callable object producing the defined value. Returns the value that will be assigned to the defined column.
534 /// \param[in] columns Names of the columns/branches in input to the producer function (excluding slot and entry).
535 /// \return the first node of the computation graph for which the new quantity is defined.
536 ///
537 /// This alternative implementation of `Define` is meant as a helper in writing entry-specific, thread-safe custom
538 /// columns. The expression must be a callable of signature R(unsigned int, ULong64_t, T1, T2, ...) where `T1, T2...`
539 /// are the types of the columns that the expression takes as input. The first parameter is reserved for an unsigned
540 /// integer representing a "slot number". RDataFrame guarantees that different threads will invoke the expression with
541 /// different slot numbers - slot numbers will range from zero to ROOT::GetThreadPoolSize()-1.
542 /// Note that there is no guarantee as to how often each slot will be reached during the event loop.
543 /// The second parameter is reserved for a `ULong64_t` representing the current entry being processed by the current thread.
544 ///
545 /// The following two `Define`s are equivalent, although `DefineSlotEntry` is slightly more performant:
546 /// ~~~{.cpp}
547 /// int function(unsigned int, ULong64_t, double, double);
548 /// Define("x", function, {"rdfslot_", "rdfentry_", "column1", "column2"})
549 /// DefineSlotEntry("x", function, {"column1", "column2"})
550 /// ~~~
551 ///
552 /// See Define() for more information.
553 template <typename F>
554 RInterface<Proxied> DefineSlotEntry(std::string_view name, F expression, const ColumnNames_t &columns = {})
555 {
556 return DefineImpl<F, RDFDetail::ExtraArgsForDefine::SlotAndEntry>(name, std::move(expression), columns,
557 "DefineSlotEntry");
558 }
559 // clang-format on
560
561 ////////////////////////////////////////////////////////////////////////////
562 /// \brief Define a new column.
563 /// \param[in] name The name of the defined column.
564 /// \param[in] expression An expression in C++ which represents the defined value
565 /// \return the first node of the computation graph for which the new quantity is defined.
566 ///
567 /// The expression is just-in-time compiled and used to produce the column entries.
568 /// It must be valid C++ syntax in which variable names are substituted with the names
569 /// of branches/columns.
570 ///
571 /// \note If the body of the string expression contains an explicit `return` statement (even if it is in a nested
572 /// scope), RDataFrame _will not_ add another one in front of the expression. So this will not work:
573 /// ~~~{.cpp}
574 /// df.Define("x2", "Map(v, [](float e) { return e*e; })")
575 /// ~~~
576 /// but instead this will:
577 /// ~~~{.cpp}
578 /// df.Define("x2", "return Map(v, [](float e) { return e*e; })")
579 /// ~~~
580 ///
581 /// Refer to the first overload of this method for the full documentation.
582 RInterface<Proxied> Define(std::string_view name, std::string_view expression)
583 {
584 constexpr auto where = "Define";
585 RDFInternal::CheckValidCppVarName(name, where);
586 // these checks must be done before jitting lest we throw exceptions in jitted code
587 RDFInternal::CheckForRedefinition(where, name, fColRegister,
589
590 auto jittedDefine = RDFInternal::BookDefineJit(name, expression, *fLoopManager, GetDataSource(), fColRegister);
591
593 newCols.AddDefine(std::move(jittedDefine));
594
595 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newCols));
596
597 return newInterface;
598 }
599
600 ////////////////////////////////////////////////////////////////////////////
601 /// \brief Overwrite the value and/or type of an existing column.
602 /// \param[in] name The name of the column to redefine.
603 /// \param[in] expression Function, lambda expression, functor class or any other callable object producing the defined value. Returns the value that will be assigned to the defined column.
604 /// \param[in] columns Names of the columns/branches in input to the expression.
605 /// \return the first node of the computation graph for which the quantity is redefined.
606 ///
607 /// The old value of the column can be used as an input for the expression.
608 ///
609 /// An exception is thrown in case the column to redefine does not already exist.
610 /// See Define() for more information.
611 template <typename F, std::enable_if_t<!std::is_convertible<F, std::string>::value, int> = 0>
612 RInterface<Proxied> Redefine(std::string_view name, F expression, const ColumnNames_t &columns = {})
613 {
614 return DefineImpl<F, RDFDetail::ExtraArgsForDefine::None>(name, std::move(expression), columns, "Redefine");
615 }
616
617 // clang-format off
618 ////////////////////////////////////////////////////////////////////////////
619 /// \brief Overwrite the value and/or type of an existing column.
620 /// \param[in] name The name of the column to redefine.
621 /// \param[in] expression Function, lambda expression, functor class or any other callable object producing the defined value. Returns the value that will be assigned to the defined column.
622 /// \param[in] columns Names of the columns/branches in input to the producer function (excluding slot).
623 /// \return the first node of the computation graph for which the new quantity is defined.
624 ///
625 /// The old value of the column can be used as an input for the expression.
626 /// An exception is thrown in case the column to redefine does not already exist.
627 ///
628 /// See DefineSlot() for more information.
629 // clang-format on
630 template <typename F>
631 RInterface<Proxied> RedefineSlot(std::string_view name, F expression, const ColumnNames_t &columns = {})
632 {
633 return DefineImpl<F, RDFDetail::ExtraArgsForDefine::Slot>(name, std::move(expression), columns, "RedefineSlot");
634 }
635
636 // clang-format off
637 ////////////////////////////////////////////////////////////////////////////
638 /// \brief Overwrite the value and/or type of an existing column.
639 /// \param[in] name The name of the column to redefine.
640 /// \param[in] expression Function, lambda expression, functor class or any other callable object producing the defined value. Returns the value that will be assigned to the defined column.
641 /// \param[in] columns Names of the columns/branches in input to the producer function (excluding slot and entry).
642 /// \return the first node of the computation graph for which the new quantity is defined.
643 ///
644 /// The old value of the column can be used as an input for the expression.
645 /// An exception is thrown in case the column to re-define does not already exist.
646 ///
647 /// See DefineSlotEntry() for more information.
648 // clang-format on
649 template <typename F>
650 RInterface<Proxied> RedefineSlotEntry(std::string_view name, F expression, const ColumnNames_t &columns = {})
651 {
652 return DefineImpl<F, RDFDetail::ExtraArgsForDefine::SlotAndEntry>(name, std::move(expression), columns,
653 "RedefineSlotEntry");
654 }
655
656 ////////////////////////////////////////////////////////////////////////////
657 /// \brief Overwrite the value and/or type of an existing column.
658 /// \param[in] name The name of the column to redefine.
659 /// \param[in] expression An expression in C++ which represents the defined value
660 /// \return the first node of the computation graph for which the new quantity is defined.
661 ///
662 /// The expression is just-in-time compiled and used to produce the column entries.
663 /// It must be valid C++ syntax in which variable names are substituted with the names
664 /// of branches/columns.
665 ///
666 /// The old value of the column can be used as an input for the expression.
667 /// An exception is thrown in case the column to re-define does not already exist.
668 ///
669 /// Aliases cannot be overridden. See the corresponding Define() overload for more information.
670 RInterface<Proxied> Redefine(std::string_view name, std::string_view expression)
671 {
672 constexpr auto where = "Redefine";
673 RDFInternal::CheckValidCppVarName(name, where);
674 RDFInternal::CheckForDefinition(where, name, fColRegister,
676 RDFInternal::CheckForNoVariations(where, name, fColRegister);
677
678 auto jittedDefine = RDFInternal::BookDefineJit(name, expression, *fLoopManager, GetDataSource(), fColRegister);
679
681 newCols.AddDefine(std::move(jittedDefine));
682
683 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newCols));
684
685 return newInterface;
686 }
687
688 ////////////////////////////////////////////////////////////////////////////
689 /// \brief In case the value in the given column is missing, provide a default value
690 /// \tparam T The type of the column
691 /// \param[in] column Column name where missing values should be replaced by the given default value
692 /// \param[in] defaultValue Value to provide instead of a missing value
693 /// \return The node of the graph that will provide a default value
694 ///
695 /// This operation is useful in case an entry of the dataset is incomplete,
696 /// i.e. if one or more of the columns do not have valid values. It does not
697 /// modify the values of the column, but in case any entry is missing, it
698 /// will provide the default value to downstream nodes instead.
699 ///
700 /// Use cases include:
701 /// * When processing multiple files, one or more of them is missing a column
702 /// * In horizontal joining with entry matching, a certain dataset has no
703 /// match for the current entry.
704 ///
705 /// ### Example usage:
706 ///
707 /// \code{.cpp}
708 /// // Assume a dataset with columns [idx, x] matching another dataset with
709 /// // columns [idx, y]. For idx == 42, the right-hand dataset has no match
710 /// ROOT::RDataFrame df{dataset};
711 /// auto df_default = df.DefaultValueFor("y", 33)
712 /// .Define("z", [](int x, int y) { return x + y; }, {"x", "y"});
713 /// auto colz = df_default.Take<int>("z");
714 /// \endcode
715 ///
716 /// \code{.py}
717 /// df = ROOT.RDataFrame(dataset)
718 /// df_default = df.DefaultValueFor("y", 33).Define("z", "x + y")
719 /// colz = df_default.Take[int]("z")
720 /// \endcode
721 template <typename T>
722 RInterface<Proxied> DefaultValueFor(std::string_view column, const T &defaultValue)
723 {
724 constexpr auto where{"DefaultValueFor"};
725 RDFInternal::CheckForNoVariations(where, column, fColRegister);
726 // For now disable this functionality in case of an empty data source and
727 // the column name was not defined previously.
728 if (ROOT::Internal::RDF::GetDataSourceLabel(*this) == "EmptyDS")
729 RDFInternal::CheckForDefinition(where, column, fColRegister,
731
732 // Declare return type to the interpreter, for future use by jitted actions
733 auto retTypeName = RDFInternal::TypeID2TypeName(typeid(T));
734 if (retTypeName.empty()) {
735 // The type is not known to the interpreter.
736 // We must not error out here, but if/when this column is used in jitted code
737 const auto demangledType = RDFInternal::DemangleTypeIdName(typeid(T));
738 retTypeName = "CLING_UNKNOWN_TYPE_" + demangledType;
739 }
740
741 const auto validColumnNames = ColumnNames_t{column.data()};
742 auto newColumn = std::make_shared<ROOT::Internal::RDF::RDefaultValueFor<T>>(
743 column, retTypeName, defaultValue, validColumnNames, fColRegister, *fLoopManager);
744 CheckAndFillDSColumns(validColumnNames, TTraits::TypeList<T>{});
745
747 newCols.AddDefine(std::move(newColumn));
748
749 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newCols));
750
751 return newInterface;
752 }
753
754 // clang-format off
755 ////////////////////////////////////////////////////////////////////////////
756 /// \brief Define a new column that is updated when the input sample changes.
757 /// \param[in] name The name of the defined column.
758 /// \param[in] expression A C++ callable that computes the new value of the defined column.
759 /// \return the first node of the computation graph for which the new quantity is defined.
760 ///
761 /// The signature of the callable passed as second argument should be `T(unsigned int slot, const ROOT::RDF::RSampleInfo &id)`
762 /// where:
763 /// - `T` is the type of the defined column
764 /// - `slot` is a number in the range [0, nThreads) that is different for each processing thread. This can simplify
765 /// the definition of thread-safe callables if you are interested in using parallel capabilities of RDataFrame.
766 /// - `id` is an instance of a ROOT::RDF::RSampleInfo object which contains information about the sample which is
767 /// being processed (see the class docs for more information).
768 ///
769 /// DefinePerSample() is useful to e.g. define a quantity that depends on which TTree in which TFile is being
770 /// processed or to inject a callback into the event loop that is only called when the processing of a new sample
771 /// starts rather than at every entry.
772 ///
773 /// The callable will be invoked once per input TTree or once per multi-thread task, whichever is more often.
774 ///
775 /// ### Example usage:
776 /// ~~~{.cpp}
777 /// ROOT::RDataFrame df{"mytree", {"sample1.root","sample2.root"}};
778 /// df.DefinePerSample("weightbysample",
779 /// [](unsigned int slot, const ROOT::RDF::RSampleInfo &id)
780 /// { return id.Contains("sample1") ? 1.0f : 2.0f; });
781 /// ~~~
782 // clang-format on
783 // TODO we could SFINAE on F's signature to provide friendlier compilation errors in case of signature mismatch
784 template <typename F, typename RetType_t = typename TTraits::CallableTraits<F>::ret_type>
785 RInterface<Proxied> DefinePerSample(std::string_view name, F expression)
786 {
787 return DefinePerSampleImpl<F, RetType_t>(name, std::move(expression), false);
788 }
789
790 ////////////////////////////////////////////////////////////////////////////
791 /// \brief Redefine an existing column that is updated when the input sample changes.
792 /// \sa DefinePerSample. Works similarly, but the column must already exist and will be overwritten.
793 template <typename F, typename RetType_t = typename TTraits::CallableTraits<F>::ret_type>
794 RInterface<Proxied> RedefinePerSample(std::string_view name, F expression)
795 {
796 return DefinePerSampleImpl<F, RetType_t>(name, std::move(expression), true);
797 }
798
799 // clang-format off
800 ////////////////////////////////////////////////////////////////////////////
801 /// \brief Define a new column that is updated when the input sample changes.
802 /// \param[in] name The name of the defined column.
803 /// \param[in] expression A valid C++ expression as a string, which will be used to compute the defined value.
804 /// \return the first node of the computation graph for which the new quantity is defined.
805 ///
806 /// The expression is just-in-time compiled and used to produce the column entries.
807 /// It must be valid C++ syntax and the usage of the special variable names `rdfslot_` and `rdfsampleinfo_` is
808 /// permitted, where these variables will take the same values as the `slot` and `id` parameters described at the
809 /// DefinePerSample(std::string_view name, F expression) overload. See the documentation of that overload for more information.
810 ///
811 /// ### Example usage:
812 /// ~~~{.py}
813 /// df = ROOT.RDataFrame('mytree', ['sample1.root','sample2.root'])
814 /// df.DefinePerSample('weightbysample', 'rdfsampleinfo_.Contains("sample1") ? 1.0f : 2.0f')
815 /// ~~~
816 ///
817 /// \note
818 /// If you have declared some C++ function to the interpreter, the correct syntax to call that function with this
819 /// overload of DefinePerSample is by calling it explicitly with the special names `rdfslot_` and `rdfsampleinfo_` as
820 /// input parameters. This is for example the correct way to call this overload when working in PyROOT:
821 /// ~~~{.py}
822 /// ROOT.gInterpreter.Declare(
823 /// """
824 /// float weights(unsigned int slot, const ROOT::RDF::RSampleInfo &id){
825 /// return id.Contains("sample1") ? 1.0f : 2.0f;
826 /// }
827 /// """)
828 /// df = ROOT.RDataFrame("mytree", ["sample1.root","sample2.root"])
829 /// df.DefinePerSample("weightsbysample", "weights(rdfslot_, rdfsampleinfo_)")
830 /// ~~~
831 ///
832 /// \note
833 /// Differently from what happens in Define(), the string expression passed to DefinePerSample cannot contain
834 /// column names other than those mentioned above: the expression is evaluated once before the processing of the
835 /// sample even starts, so column values are not accessible.
836 // clang-format on
837 RInterface<Proxied> DefinePerSample(std::string_view name, std::string_view expression)
838 {
839 return DefinePerSampleJitImpl(name, expression, false);
840 }
841
842 ////////////////////////////////////////////////////////////////////////////
843 /// \brief Redefine an existing column that is updated when the input sample changes.
844 /// \sa DefinePerSample. Works similarly, but the column must already exist and will be overwritten.
845 RInterface<Proxied> RedefinePerSample(std::string_view name, std::string_view expression)
846 {
847 return DefinePerSampleJitImpl(name, expression, true);
848 }
849
850 /// \brief Register systematic variations for a single existing column using custom variation tags.
851 /// \param[in] colName name of the column for which varied values are provided.
852 /// \param[in] expression a callable that evaluates the varied values for the specified columns. The callable can
853 /// take any column values as input, similarly to what happens during Filter and Define calls. It must
854 /// return an RVec of varied values, one for each variation tag, in the same order as the tags.
855 /// \param[in] inputColumns the names of the columns to be passed to the callable.
856 /// \param[in] variationTags names for each of the varied values, e.g. `"up"` and `"down"`.
857 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
858 ///
859 /// Vary provides a natural and flexible syntax to define systematic variations that automatically propagate to
860 /// Filters, Defines and results. RDataFrame usage of columns with attached variations does not change, but for
861 /// results that depend on any varied quantity, a map/dictionary of varied results can be produced with
862 /// ROOT::RDF::Experimental::VariationsFor (see the example below).
863 ///
864 /// The dictionary will contain a "nominal" value (accessed with the "nominal" key) for the unchanged result, and
865 /// values for each of the systematic variations that affected the result (via upstream Filters or via direct or
866 /// indirect dependencies of the column values on some registered variations). The keys will be a composition of
867 /// variation names and tags, e.g. "pt:up" and "pt:down" for the example below.
868 ///
869 /// In the following example we add up/down variations of pt and fill a histogram with a quantity that depends on pt.
870 /// We automatically obtain three histograms in output ("nominal", "pt:up" and "pt:down"):
871 /// ~~~{.cpp}
872 /// auto nominal_hx =
873 /// df.Vary("pt", [] (double pt) { return RVecD{pt*0.9, pt*1.1}; }, {"down", "up"})
874 /// .Filter("pt > k")
875 /// .Define("x", someFunc, {"pt"})
876 /// .Histo1D("x");
877 ///
878 /// auto hx = ROOT::RDF::Experimental::VariationsFor(nominal_hx);
879 /// hx["nominal"].Draw();
880 /// hx["pt:down"].Draw("SAME");
881 /// hx["pt:up"].Draw("SAME");
882 /// ~~~
883 /// RDataFrame computes all variations as part of a single loop over the data.
884 /// In particular, this means that I/O and computation of values shared
885 /// among variations only happen once for all variations. Thus, the event loop
886 /// run-time typically scales much better than linearly with the number of
887 /// variations.
888 ///
889 /// RDataFrame lazily computes the varied values required to produce the
890 /// outputs of \ref ROOT::RDF::Experimental::VariationsFor "VariationsFor()". If \ref
891 /// ROOT::RDF::Experimental::VariationsFor "VariationsFor()" was not called for a result, the computations are only
892 /// run for the nominal case.
893 ///
894 /// See other overloads for examples when variations are added for multiple existing columns,
895 /// or when the tags are auto-generated instead of being directly defined.
896 template <typename F>
897 RInterface<Proxied> Vary(std::string_view colName, F &&expression, const ColumnNames_t &inputColumns,
898 const std::vector<std::string> &variationTags, std::string_view variationName = "")
899 {
900 std::vector<std::string> colNames{{std::string(colName)}};
901 const std::string theVariationName{variationName.empty() ? colName : variationName};
902
903 return VaryImpl<true>(std::move(colNames), std::forward<F>(expression), inputColumns, variationTags,
904 theVariationName);
905 }
906
907 /// \brief Register systematic variations for a single existing column using auto-generated variation tags.
908 /// \param[in] colName name of the column for which varied values are provided.
909 /// \param[in] expression a callable that evaluates the varied values for the specified columns. The callable can
910 /// take any column values as input, similarly to what happens during Filter and Define calls. It must
911 /// return an RVec of varied values, one for each variation tag, in the same order as the tags.
912 /// \param[in] inputColumns the names of the columns to be passed to the callable.
913 /// \param[in] nVariations number of variations returned by the expression. The corresponding tags will be `"0"`,
914 /// `"1"`, etc.
915 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
916 /// colName is used if none is provided.
917 ///
918 /// This overload of Vary takes an nVariations parameter instead of a list of tag names.
919 /// The varied results will be accessible via the keys of the dictionary with the form `variationName:N` where `N`
920 /// is the corresponding sequential tag starting at 0 and going up to `nVariations - 1`.
921 ///
922 /// Example usage:
923 /// ~~~{.cpp}
924 /// auto nominal_hx =
925 /// df.Vary("pt", [] (double pt) { return RVecD{pt*0.9, pt*1.1}; }, 2)
926 /// .Histo1D("x");
927 ///
928 /// auto hx = ROOT::RDF::Experimental::VariationsFor(nominal_hx);
929 /// hx["nominal"].Draw();
930 /// hx["x:0"].Draw("SAME");
931 /// hx["x:1"].Draw("SAME");
932 /// ~~~
933 ///
934 /// \note See also This Vary() overload for more information.
935 template <typename F>
936 RInterface<Proxied> Vary(std::string_view colName, F &&expression, const ColumnNames_t &inputColumns,
937 std::size_t nVariations, std::string_view variationName = "")
938 {
939 R__ASSERT(nVariations > 0 && "Must have at least one variation.");
940
941 std::vector<std::string> variationTags;
942 variationTags.reserve(nVariations);
943 for (std::size_t i = 0u; i < nVariations; ++i)
944 variationTags.emplace_back(std::to_string(i));
945
946 const std::string theVariationName{variationName.empty() ? colName : variationName};
947
948 return Vary(colName, std::forward<F>(expression), inputColumns, std::move(variationTags), theVariationName);
949 }
950
951 /// \brief Register systematic variations for multiple existing columns using custom variation tags.
952 /// \param[in] colNames set of names of the columns for which varied values are provided.
953 /// \param[in] expression a callable that evaluates the varied values for the specified columns. The callable can
954 /// take any column values as input, similarly to what happens during Filter and Define calls. It must
955 /// return an RVec of varied values, one for each variation tag, in the same order as the tags.
956 /// \param[in] inputColumns the names of the columns to be passed to the callable.
957 /// \param[in] variationTags names for each of the varied values, e.g. `"up"` and `"down"`.
958 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`
959 ///
960 /// This overload of Vary takes a list of column names as first argument and
961 /// requires that the expression returns an RVec of RVecs of values: one inner RVec for the variations of each
962 /// affected column. The `variationTags` are defined as `{"down", "up"}`.
963 ///
964 /// Example usage:
965 /// ~~~{.cpp}
966 /// // produce variations "ptAndEta:down" and "ptAndEta:up"
967 /// auto nominal_hx =
968 /// df.Vary({"pt", "eta"}, // the columns that will vary simultaneously
969 /// [](double pt, double eta) { return RVec<RVecF>{{pt*0.9, pt*1.1}, {eta*0.9, eta*1.1}}; },
970 /// {"pt", "eta"}, // inputs to the Vary expression, independent of what columns are varied
971 /// {"down", "up"}, // variation tags
972 /// "ptAndEta") // variation name
973 /// .Histo1D("pt", "eta");
974 ///
975 /// auto hx = ROOT::RDF::Experimental::VariationsFor(nominal_hx);
976 /// hx["nominal"].Draw();
977 /// hx["ptAndEta:down"].Draw("SAME");
978 /// hx["ptAndEta:up"].Draw("SAME");
979 /// ~~~
980 ///
981 /// \note See also This Vary() overload for more information.
982
983 template <typename F>
984 RInterface<Proxied> Vary(const std::vector<std::string> &colNames, F &&expression, const ColumnNames_t &inputColumns,
985 const std::vector<std::string> &variationTags, std::string_view variationName)
986 {
987 return VaryImpl<false>(colNames, std::forward<F>(expression), inputColumns, variationTags, variationName);
988 }
989
990 /// \brief Register systematic variations for multiple existing columns using custom variation tags.
991 /// \param[in] colNames set of names of the columns for which varied values are provided.
992 /// \param[in] expression a callable that evaluates the varied values for the specified columns. The callable can
993 /// take any column values as input, similarly to what happens during Filter and Define calls. It must
994 /// return an RVec of varied values, one for each variation tag, in the same order as the tags.
995 /// \param[in] inputColumns the names of the columns to be passed to the callable.
996 /// \param[in] variationTags names for each of the varied values, e.g. `"up"` and `"down"`.
997 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
998 /// colName is used if none is provided.
999 ///
1000 /// \note This overload ensures that the ambiguity between C++20 string, vector<string> construction from init list
1001 /// is avoided.
1002 ///
1003 /// \note See also This Vary() overload for more information.
1004 template <typename F>
1006 Vary(std::initializer_list<std::string> colNames, F &&expression, const ColumnNames_t &inputColumns,
1007 const std::vector<std::string> &variationTags, std::string_view variationName)
1008 {
1009 return Vary(std::vector<std::string>(colNames), std::forward<F>(expression), inputColumns, variationTags, variationName);
1010 }
1011
1012 /// \brief Register systematic variations for multiple existing columns using auto-generated tags.
1013 /// \param[in] colNames set of names of the columns for which varied values are provided.
1014 /// \param[in] expression a callable that evaluates the varied values for the specified columns. The callable can
1015 /// take any column values as input, similarly to what happens during Filter and Define calls. It must
1016 /// return an RVec of varied values, one for each variation tag, in the same order as the tags.
1017 /// \param[in] inputColumns the names of the columns to be passed to the callable.
1018 /// \param[in] nVariations number of variations returned by the expression. The corresponding tags will be `"0"`,
1019 /// `"1"`, etc.
1020 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
1021 /// colName is used if none is provided.
1022 ///
1023 /// This overload of Vary takes a list of column names as first argument.
1024 /// It takes an `nVariations` parameter instead of a list of tag names (`variationTags`). Tag names
1025 /// will be auto-generated as the sequence 0...``nVariations-1``.
1026 ///
1027 /// Example usage:
1028 /// ~~~{.cpp}
1029 /// auto nominal_hx =
1030 /// df.Vary({"pt", "eta"}, // the columns that will vary simultaneously
1031 /// [](double pt, double eta) { return RVec<RVecF>{{pt*0.9, pt*1.1}, {eta*0.9, eta*1.1}}; },
1032 /// {"pt", "eta"}, // inputs to the Vary expression, independent of what columns are varied
1033 /// 2, // auto-generated variation tags
1034 /// "ptAndEta") // variation name
1035 /// .Histo1D("pt", "eta");
1036 ///
1037 /// auto hx = ROOT::RDF::Experimental::VariationsFor(nominal_hx);
1038 /// hx["nominal"].Draw();
1039 /// hx["ptAndEta:0"].Draw("SAME");
1040 /// hx["ptAndEta:1"].Draw("SAME");
1041 /// ~~~
1042 ///
1043 /// \note See also This Vary() overload for more information.
1044 template <typename F>
1045 RInterface<Proxied> Vary(const std::vector<std::string> &colNames, F &&expression, const ColumnNames_t &inputColumns,
1046 std::size_t nVariations, std::string_view variationName)
1047 {
1048 R__ASSERT(nVariations > 0 && "Must have at least one variation.");
1049
1050 std::vector<std::string> variationTags;
1051 variationTags.reserve(nVariations);
1052 for (std::size_t i = 0u; i < nVariations; ++i)
1053 variationTags.emplace_back(std::to_string(i));
1054
1055 return Vary(colNames, std::forward<F>(expression), inputColumns, std::move(variationTags), variationName);
1056 }
1057
1058 /// \brief Register systematic variations for for multiple existing columns using custom variation tags.
1059 /// \param[in] colNames set of names of the columns for which varied values are provided.
1060 /// \param[in] expression a callable that evaluates the varied values for the specified columns. The callable can
1061 /// take any column values as input, similarly to what happens during Filter and Define calls. It must
1062 /// return an RVec of varied values, one for each variation tag, in the same order as the tags.
1063 /// \param[in] inputColumns the names of the columns to be passed to the callable.
1064 /// \param[in] inputColumns the names of the columns to be passed to the callable.
1065 /// \param[in] nVariations number of variations returned by the expression. The corresponding tags will be `"0"`,
1066 /// `"1"`, etc.
1067 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
1068 /// colName is used if none is provided.
1069 ///
1070 /// \note This overload ensures that the ambiguity between C++20 string, vector<string> construction from init list
1071 /// is avoided.
1072 ///
1073 /// \note See also This Vary() overload for more information.
1074 template <typename F>
1075 RInterface<Proxied> Vary(std::initializer_list<std::string> colNames, F &&expression,
1076 const ColumnNames_t &inputColumns, std::size_t nVariations, std::string_view variationName)
1077 {
1078 return Vary(std::vector<std::string>(colNames), std::forward<F>(expression), inputColumns, nVariations, variationName);
1079 }
1080
1081 /// \brief Register systematic variations for a single existing column using custom variation tags.
1082 /// \param[in] colName name of the column for which varied values are provided.
1083 /// \param[in] expression a string containing valid C++ code that evaluates to an RVec containing the varied
1084 /// values for the specified column.
1085 /// \param[in] variationTags names for each of the varied values, e.g. `"up"` and `"down"`.
1086 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
1087 /// colName is used if none is provided.
1088 ///
1089 /// This overload adds the possibility for the expression used to evaluate the varied values to be just-in-time
1090 /// compiled. The example below shows how Vary() is used while dealing with a single column. The variation tags are
1091 /// defined as `{"down", "up"}`.
1092 /// ~~~{.cpp}
1093 /// auto nominal_hx =
1094 /// df.Vary("pt", "ROOT::RVecD{pt*0.9, pt*1.1}", {"down", "up"})
1095 /// .Filter("pt > k")
1096 /// .Define("x", someFunc, {"pt"})
1097 /// .Histo1D("x");
1098 ///
1099 /// auto hx = ROOT::RDF::Experimental::VariationsFor(nominal_hx);
1100 /// hx["nominal"].Draw();
1101 /// hx["pt:down"].Draw("SAME");
1102 /// hx["pt:up"].Draw("SAME");
1103 /// ~~~
1104 ///
1105 /// ## Short-hand expression syntax
1106 ///
1107 /// For convenience, when a C++ expression is passed to Vary, the return type can be omitted if the string begins
1108 /// with '{' and ends with '}' (whitespace, tab and newline characters are excluded from the search). This means that
1109 /// the following is equivalent to the example above:
1110 ///
1111 /// ~~~{.cpp}
1112 /// auto nominal_hx =
1113 /// df.Vary("pt", "{pt*0.9, pt*1.1}", {"down", "up"})
1114 /// // Same as above
1115 /// ~~~
1116 ///
1117 /// \note See also This Vary() overload for more information.
1118 RInterface<Proxied> Vary(std::string_view colName, std::string_view expression,
1119 const std::vector<std::string> &variationTags, std::string_view variationName = "")
1120 {
1121 std::vector<std::string> colNames{{std::string(colName)}};
1122 const std::string theVariationName{variationName.empty() ? colName : variationName};
1123
1124 return JittedVaryImpl(colNames, expression, variationTags, theVariationName, /*isSingleColumn=*/true);
1125 }
1126
1127 /// \brief Register systematic variations for a single existing column using auto-generated variation tags.
1128 /// \param[in] colName name of the column for which varied values are provided.
1129 /// \param[in] expression a string containing valid C++ code that evaluates to an RVec containing the varied
1130 /// values for the specified column.
1131 /// \param[in] nVariations number of variations returned by the expression. The corresponding tags will be `"0"`,
1132 /// `"1"`, etc.
1133 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
1134 /// colName is used if none is provided.
1135 ///
1136 /// This overload adds the possibility for the expression used to evaluate the varied values to be a just-in-time
1137 /// compiled. The example below shows how Vary() is used while dealing with a single column. The variation tags are
1138 /// auto-generated.
1139 /// ~~~{.cpp}
1140 /// auto nominal_hx =
1141 /// df.Vary("pt", "ROOT::RVecD{pt*0.9, pt*1.1}", 2)
1142 /// .Histo1D("pt");
1143 ///
1144 /// auto hx = ROOT::RDF::Experimental::VariationsFor(nominal_hx);
1145 /// hx["nominal"].Draw();
1146 /// hx["pt:0"].Draw("SAME");
1147 /// hx["pt:1"].Draw("SAME");
1148 /// ~~~
1149 ///
1150 /// ## Short-hand expression syntax
1151 ///
1152 /// For convenience, when a C++ expression is passed to Vary, the return type can be omitted if the string begins
1153 /// with '{' and ends with '}' (whitespace, tab and newline characters are excluded from the search). This means that
1154 /// the following is equivalent to the example above:
1155 ///
1156 /// ~~~{.cpp}
1157 /// auto nominal_hx =
1158 /// df.Vary("pt", "{pt*0.9, pt*1.1}", 2)
1159 /// // Same as above
1160 /// ~~~
1161 ///
1162 /// \note See also This Vary() overload for more information.
1163 RInterface<Proxied> Vary(std::string_view colName, std::string_view expression, std::size_t nVariations,
1164 std::string_view variationName = "")
1165 {
1166 std::vector<std::string> variationTags;
1167 variationTags.reserve(nVariations);
1168 for (std::size_t i = 0u; i < nVariations; ++i)
1169 variationTags.emplace_back(std::to_string(i));
1170
1171 return Vary(colName, expression, std::move(variationTags), variationName);
1172 }
1173
1174 /// \brief Register systematic variations for multiple existing columns using auto-generated variation tags.
1175 /// \param[in] colNames set of names of the columns for which varied values are provided.
1176 /// \param[in] expression a string containing valid C++ code that evaluates to an RVec or RVecs containing the varied
1177 /// values for the specified columns.
1178 /// \param[in] nVariations number of variations returned by the expression. The corresponding tags will be `"0"`,
1179 /// `"1"`, etc.
1180 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
1181 ///
1182 /// This overload adds the possibility for the expression used to evaluate the varied values to be just-in-time
1183 /// compiled. It takes an nVariations parameter instead of a list of tag names.
1184 /// The varied results will be accessible via the keys of the dictionary with the form `variationName:N` where `N`
1185 /// is the corresponding sequential tag starting at 0 and going up to `nVariations - 1`.
1186 /// The example below shows how Vary() is used while dealing with multiple columns.
1187 ///
1188 /// ~~~{.cpp}
1189 /// auto nominal_hx =
1190 /// df.Vary({"x", "y"}, "ROOT::RVec<ROOT::RVecD>{{x*0.9, x*1.1}, {y*0.9, y*1.1}}", 2, "xy")
1191 /// .Histo1D("x", "y");
1192 ///
1193 /// auto hx = ROOT::RDF::Experimental::VariationsFor(nominal_hx);
1194 /// hx["nominal"].Draw();
1195 /// hx["xy:0"].Draw("SAME");
1196 /// hx["xy:1"].Draw("SAME");
1197 /// ~~~
1198 ///
1199 /// ## Short-hand expression syntax
1200 ///
1201 /// For convenience, when a C++ expression is passed to Vary, the return type can be omitted if the string begins
1202 /// with '{' and ends with '}' (whitespace, tab and newline characters are excluded from the search). This means that
1203 /// the following is equivalent to the example above:
1204 ///
1205 /// ~~~{.cpp}
1206 /// auto nominal_hx =
1207 /// df.Vary("pt", "{{x*0.9, x*1.1}, {y*0.9, y*1.1}}", 2, "xy")
1208 /// // Same as above
1209 /// ~~~
1210 ///
1211 /// or also:
1212 ///
1213 /// ~~~{.cpp}
1214 /// auto nominal_hx =
1215 /// df.Vary("pt", R"(
1216 /// {
1217 /// {x*0.9, x*1.1}, // x variations
1218 /// {y*0.9, y*1.1} // y variations
1219 /// }
1220 /// )", 2, "xy")
1221 /// // Same as above
1222 /// ~~~
1223 ///
1224 /// \note See also This Vary() overload for more information.
1225 RInterface<Proxied> Vary(const std::vector<std::string> &colNames, std::string_view expression,
1226 std::size_t nVariations, std::string_view variationName)
1227 {
1228 std::vector<std::string> variationTags;
1229 variationTags.reserve(nVariations);
1230 for (std::size_t i = 0u; i < nVariations; ++i)
1231 variationTags.emplace_back(std::to_string(i));
1232
1233 return Vary(colNames, expression, std::move(variationTags), variationName);
1234 }
1235
1236 /// \brief Register systematic variations for multiple existing columns using auto-generated variation tags.
1237 /// \param[in] colNames set of names of the columns for which varied values are provided.
1238 /// \param[in] expression a string containing valid C++ code that evaluates to an RVec containing the varied
1239 /// values for the specified column.
1240 /// \param[in] nVariations number of variations returned by the expression. The corresponding tags will be `"0"`,
1241 /// `"1"`, etc.
1242 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
1243 /// colName is used if none is provided.
1244 ///
1245 /// \note This overload ensures that the ambiguity between C++20 string, vector<string> construction from init list
1246 /// is avoided.
1247 ///
1248 /// \note See also This Vary() overload for more information.
1249 RInterface<Proxied> Vary(std::initializer_list<std::string> colNames, std::string_view expression,
1250 std::size_t nVariations, std::string_view variationName)
1251 {
1252 return Vary(std::vector<std::string>(colNames), expression, nVariations, variationName);
1253 }
1254
1255 /// \brief Register systematic variations for multiple existing columns using custom variation tags.
1256 /// \param[in] colNames set of names of the columns for which varied values are provided.
1257 /// \param[in] expression a string containing valid C++ code that evaluates to an RVec or RVecs containing the varied
1258 /// values for the specified columns.
1259 /// \param[in] variationTags names for each of the varied values, e.g. `"up"` and `"down"`.
1260 /// \param[in] variationName a generic name for this set of varied values, e.g. `"ptvariation"`.
1261 ///
1262 /// This overload adds the possibility for the expression used to evaluate the varied values to be just-in-time
1263 /// compiled. The example below shows how Vary() is used while dealing with multiple columns. The tags are defined as
1264 /// `{"down", "up"}`.
1265 /// ~~~{.cpp}
1266 /// auto nominal_hx =
1267 /// df.Vary({"x", "y"}, "ROOT::RVec<ROOT::RVecD>{{x*0.9, x*1.1}, {y*0.9, y*1.1}}", {"down", "up"}, "xy")
1268 /// .Histo1D("x", "y");
1269 ///
1270 /// auto hx = ROOT::RDF::Experimental::VariationsFor(nominal_hx);
1271 /// hx["nominal"].Draw();
1272 /// hx["xy:down"].Draw("SAME");
1273 /// hx["xy:up"].Draw("SAME");
1274 /// ~~~
1275 ///
1276 /// ## Short-hand expression syntax
1277 ///
1278 /// For convenience, when a C++ expression is passed to Vary, the return type can be omitted if the string begins
1279 /// with '{' and ends with '}' (whitespace, tab and newline characters are excluded from the search). This means that
1280 /// the following is equivalent to the example above:
1281 ///
1282 /// ~~~{.cpp}
1283 /// auto nominal_hx =
1284 /// df.Vary("pt", "{{x*0.9, x*1.1}, {y*0.9, y*1.1}}", {"down", "up"}, "xy")
1285 /// // Same as above
1286 /// ~~~
1287 ///
1288 /// or also:
1289 ///
1290 /// ~~~{.cpp}
1291 /// auto nominal_hx =
1292 /// df.Vary("pt", R"(
1293 /// {
1294 /// {x*0.9, x*1.1}, // x variations
1295 /// {y*0.9, y*1.1} // y variations
1296 /// }
1297 /// )", {"down", "up"}, "xy")
1298 /// // Same as above
1299 /// ~~~
1300 ///
1301 /// \note See also This Vary() overload for more information.
1302 RInterface<Proxied> Vary(const std::vector<std::string> &colNames, std::string_view expression,
1303 const std::vector<std::string> &variationTags, std::string_view variationName)
1304 {
1305 return JittedVaryImpl(colNames, expression, variationTags, variationName, /*isSingleColumn=*/false);
1306 }
1307
1308 ////////////////////////////////////////////////////////////////////////////
1309 /// \brief Allow to refer to a column with a different name.
1310 /// \param[in] alias name of the column alias
1311 /// \param[in] columnName of the column to be aliased
1312 /// \return the first node of the computation graph for which the alias is available.
1313 ///
1314 /// Aliasing an alias is supported.
1315 ///
1316 /// ### Example usage:
1317 /// ~~~{.cpp}
1318 /// auto df_with_alias = df.Alias("simple_name", "very_long&complex_name!!!");
1319 /// ~~~
1320 RInterface<Proxied> Alias(std::string_view alias, std::string_view columnName)
1321 {
1322 // The symmetry with Define is clear. We want to:
1323 // - Create globally the alias and return this very node, unchanged
1324 // - Make aliases accessible based on chains and not globally
1325
1326 // Helper to find out if a name is a column
1327 auto &dsColumnNames = GetDataSource() ? GetDataSource()->GetColumnNames() : ColumnNames_t{};
1328
1329 constexpr auto where = "Alias";
1330 RDFInternal::CheckValidCppVarName(alias, where);
1331 // If the alias name is a column name, there is a problem
1332 RDFInternal::CheckForRedefinition(where, alias, fColRegister, dsColumnNames);
1333
1334 const auto validColumnName = GetValidatedColumnNames(1, {std::string(columnName)})[0];
1335
1337 newCols.AddAlias(alias, validColumnName);
1338
1339 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newCols));
1340
1341 return newInterface;
1342 }
1343
1344 // clang-format off
1345 ////////////////////////////////////////////////////////////////////////////
1346 /// \brief Creates a node that filters entries based on range: [begin, end).
1347 /// \param[in] begin Initial entry number considered for this range.
1348 /// \param[in] end Final entry number (excluded) considered for this range. 0 means that the range goes until the end of the dataset.
1349 /// \param[in] stride Process one entry of the [begin, end) range every `stride` entries. Must be strictly greater than 0.
1350 /// \return the first node of the computation graph for which the event loop is limited to a certain range of entries.
1351 ///
1352 /// Note that in case of previous Ranges and Filters the selected range refers to the transformed dataset.
1353 /// Ranges are only available if EnableImplicitMT has _not_ been called. Multi-thread ranges are not supported.
1354 ///
1355 /// ### Example usage:
1356 /// ~~~{.cpp}
1357 /// auto d_0_30 = d.Range(0, 30); // Pick the first 30 entries
1358 /// auto d_15_end = d.Range(15, 0); // Pick all entries from 15 onwards
1359 /// auto d_15_end_3 = d.Range(15, 0, 3); // Stride: from event 15, pick an event every 3
1360 /// ~~~
1361 // clang-format on
1362 RInterface<RDFDetail::RRange<Proxied>> Range(unsigned int begin, unsigned int end, unsigned int stride = 1)
1363 {
1364 // check invariants
1365 if (stride == 0 || (end != 0 && end < begin))
1366 throw std::runtime_error("Range: stride must be strictly greater than 0 and end must be greater than begin.");
1367 CheckIMTDisabled("Range");
1368
1369 using Range_t = RDFDetail::RRange<Proxied>;
1370 auto rangePtr = std::make_shared<Range_t>(begin, end, stride, fProxiedPtr);
1371 RInterface<RDFDetail::RRange<Proxied>> newInterface(std::move(rangePtr), *fLoopManager, fColRegister);
1372 return newInterface;
1373 }
1374
1375 // clang-format off
1376 ////////////////////////////////////////////////////////////////////////////
1377 /// \brief Creates a node that filters entries based on range.
1378 /// \param[in] end Final entry number (excluded) considered for this range. 0 means that the range goes until the end of the dataset.
1379 /// \return a node of the computation graph for which the range is defined.
1380 ///
1381 /// See the other Range overload for a detailed description.
1382 // clang-format on
1383 RInterface<RDFDetail::RRange<Proxied>> Range(unsigned int end) { return Range(0, end, 1); }
1384
1385 /// \}
1386 // ---------------------------------------------------------------------------------
1387 // End of the doxygen group for Transformations
1388
1389 /// \name Actions
1390 /// Actions declare a type of result to be produced, for example histograms or summary statistics.
1391 /// Actions are lazy, i.e. they are only executed once a result is requested.
1392 /// \{
1393
1394 ////////////////////////////////////////////////////////////////////////////
1395 /// \brief Return the number of entries processed (*lazy action*).
1396 /// \return the number of entries wrapped in a RResultPtr.
1397 ///
1398 /// Useful e.g. for counting the number of entries passing a certain filter (see also `Report`).
1399 /// This action is *lazy*: upon invocation of this method the calculation is
1400 /// booked but not executed. Also see RResultPtr.
1401 ///
1402 /// ### Example usage:
1403 /// ~~~{.cpp}
1404 /// auto nEntriesAfterCuts = myFilteredDf.Count();
1405 /// ~~~
1406 ///
1408 {
1409 const auto nSlots = fLoopManager->GetNSlots();
1410 auto cSPtr = std::make_shared<ULong64_t>(0);
1411 using Helper_t = RDFInternal::CountHelper;
1413 auto action = std::make_unique<Action_t>(Helper_t(cSPtr, nSlots), ColumnNames_t({}), fProxiedPtr,
1415 return MakeResultPtr(cSPtr, *fLoopManager, std::move(action));
1416 }
1417
1418 ////////////////////////////////////////////////////////////////////////////
1419 /// \brief Return a collection of values of a column (*lazy action*, returns a std::vector by default).
1420 /// \tparam T The type of the column.
1421 /// \tparam COLL The type of collection used to store the values.
1422 /// \param[in] column The name of the column to collect the values of.
1423 /// \return the content of the selected column wrapped in a RResultPtr.
1424 ///
1425 /// The collection type to be specified for C-style array columns is `RVec<T>`:
1426 /// in this case the returned collection is a `std::vector<RVec<T>>`.
1427 /// ### Example usage:
1428 /// ~~~{.cpp}
1429 /// // In this case intCol is a std::vector<int>
1430 /// auto intCol = rdf.Take<int>("integerColumn");
1431 /// // Same content as above but in this case taken as a RVec<int>
1432 /// auto intColAsRVec = rdf.Take<int, RVec<int>>("integerColumn");
1433 /// // In this case intCol is a std::vector<RVec<int>>, a collection of collections
1434 /// auto cArrayIntCol = rdf.Take<RVec<int>>("cArrayInt");
1435 /// ~~~
1436 /// This action is *lazy*: upon invocation of this method the calculation is
1437 /// booked but not executed. Also see RResultPtr.
1438 template <typename T, typename COLL = std::vector<T>>
1439 RResultPtr<COLL> Take(std::string_view column = "")
1440 {
1441 const auto columns = column.empty() ? ColumnNames_t() : ColumnNames_t({std::string(column)});
1442
1443 const auto validColumnNames = GetValidatedColumnNames(1, columns);
1444 CheckAndFillDSColumns(validColumnNames, TTraits::TypeList<T>());
1445
1446 using Helper_t = RDFInternal::TakeHelper<T, T, COLL>;
1448 auto valuesPtr = std::make_shared<COLL>();
1449 const auto nSlots = fLoopManager->GetNSlots();
1450
1451 auto action =
1452 std::make_unique<Action_t>(Helper_t(valuesPtr, nSlots), validColumnNames, fProxiedPtr, fColRegister);
1453 return MakeResultPtr(valuesPtr, *fLoopManager, std::move(action));
1454 }
1455
1456 ////////////////////////////////////////////////////////////////////////////
1457 /// \brief Fill and return a one-dimensional histogram with the values of a column (*lazy action*).
1458 /// \tparam V The type of the column used to fill the histogram.
1459 /// \param[in] model The returned histogram will be constructed using this as a model.
1460 /// \param[in] vName The name of the column that will fill the histogram.
1461 /// \return the monodimensional histogram wrapped in a RResultPtr.
1462 ///
1463 /// Columns can be of a container type (e.g. `std::vector<double>`), in which case the histogram
1464 /// is filled with each one of the elements of the container. In case multiple columns of container type
1465 /// are provided (e.g. values and weights) they must have the same length for each one of the events (but
1466 /// possibly different lengths between events).
1467 /// This action is *lazy*: upon invocation of this method the calculation is
1468 /// booked but not executed. Also see RResultPtr.
1469 ///
1470 /// ### Example usage:
1471 /// ~~~{.cpp}
1472 /// // Deduce column type (this invocation needs jitting internally)
1473 /// auto myHist1 = myDf.Histo1D({"histName", "histTitle", 64u, 0., 128.}, "myColumn");
1474 /// // Explicit column type
1475 /// auto myHist2 = myDf.Histo1D<float>({"histName", "histTitle", 64u, 0., 128.}, "myColumn");
1476 /// ~~~
1477 ///
1478 /// \note Differently from other ROOT interfaces, the returned histogram is not associated to gDirectory
1479 /// and the caller is responsible for its lifetime (in particular, a typical source of confusion is that
1480 /// if result histograms go out of scope before the end of the program, ROOT might display a blank canvas).
1481 template <typename V = RDFDetail::RInferredType>
1482 RResultPtr<::TH1D> Histo1D(const TH1DModel &model = {"", "", 128u, 0., 0.}, std::string_view vName = "")
1483 {
1484 const auto userColumns = vName.empty() ? ColumnNames_t() : ColumnNames_t({std::string(vName)});
1485
1486 const auto validatedColumns = GetValidatedColumnNames(1, userColumns);
1487
1488 std::shared_ptr<::TH1D> h(nullptr);
1489 {
1490 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1491 h = model.GetHistogram();
1492 }
1493
1494 if (h->GetXaxis()->GetXmax() == h->GetXaxis()->GetXmin())
1495 h->SetCanExtend(::TH1::kAllAxes);
1496 return CreateAction<RDFInternal::ActionTags::Histo1D, V>(validatedColumns, h, h, fProxiedPtr);
1497 }
1498
1499 ////////////////////////////////////////////////////////////////////////////
1500 /// \brief Fill and return a one-dimensional histogram with the values of a column (*lazy action*).
1501 /// \tparam V The type of the column used to fill the histogram.
1502 /// \param[in] vName The name of the column that will fill the histogram.
1503 /// \return the monodimensional histogram wrapped in a RResultPtr.
1504 ///
1505 /// This overload uses a default model histogram TH1D(name, title, 128u, 0., 0.).
1506 /// The "name" and "title" strings are built starting from the input column name.
1507 /// See the description of the first Histo1D() overload for more details.
1508 ///
1509 /// ### Example usage:
1510 /// ~~~{.cpp}
1511 /// // Deduce column type (this invocation needs jitting internally)
1512 /// auto myHist1 = myDf.Histo1D("myColumn");
1513 /// // Explicit column type
1514 /// auto myHist2 = myDf.Histo1D<float>("myColumn");
1515 /// ~~~
1516 template <typename V = RDFDetail::RInferredType>
1517 RResultPtr<::TH1D> Histo1D(std::string_view vName)
1518 {
1519 const auto h_name = std::string(vName);
1520 const auto h_title = h_name + ";" + h_name + ";count";
1521 return Histo1D<V>({h_name.c_str(), h_title.c_str(), 128u, 0., 0.}, vName);
1522 }
1523
1524 ////////////////////////////////////////////////////////////////////////////
1525 /// \brief Fill and return a one-dimensional histogram with the weighted values of a column (*lazy action*).
1526 /// \tparam V The type of the column used to fill the histogram.
1527 /// \tparam W The type of the column used as weights.
1528 /// \param[in] model The returned histogram will be constructed using this as a model.
1529 /// \param[in] vName The name of the column that will fill the histogram.
1530 /// \param[in] wName The name of the column that will provide the weights.
1531 /// \return the monodimensional histogram wrapped in a RResultPtr.
1532 ///
1533 /// See the description of the first Histo1D() overload for more details.
1534 ///
1535 /// ### Example usage:
1536 /// ~~~{.cpp}
1537 /// // Deduce column type (this invocation needs jitting internally)
1538 /// auto myHist1 = myDf.Histo1D({"histName", "histTitle", 64u, 0., 128.}, "myValue", "myweight");
1539 /// // Explicit column type
1540 /// auto myHist2 = myDf.Histo1D<float, int>({"histName", "histTitle", 64u, 0., 128.}, "myValue", "myweight");
1541 /// ~~~
1542 template <typename V = RDFDetail::RInferredType, typename W = RDFDetail::RInferredType>
1543 RResultPtr<::TH1D> Histo1D(const TH1DModel &model, std::string_view vName, std::string_view wName)
1544 {
1545 const std::vector<std::string_view> columnViews = {vName, wName};
1546 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
1547 ? ColumnNames_t()
1548 : ColumnNames_t(columnViews.begin(), columnViews.end());
1549 std::shared_ptr<::TH1D> h(nullptr);
1550 {
1551 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1552 h = model.GetHistogram();
1553 }
1554
1555 if (h->GetXaxis()->GetXmax() == h->GetXaxis()->GetXmin())
1556 h->SetCanExtend(::TH1::kAllAxes);
1557 return CreateAction<RDFInternal::ActionTags::Histo1D, V, W>(userColumns, h, h, fProxiedPtr);
1558 }
1559
1560 ////////////////////////////////////////////////////////////////////////////
1561 /// \brief Fill and return a one-dimensional histogram with the weighted values of a column (*lazy action*).
1562 /// \tparam V The type of the column used to fill the histogram.
1563 /// \tparam W The type of the column used as weights.
1564 /// \param[in] vName The name of the column that will fill the histogram.
1565 /// \param[in] wName The name of the column that will provide the weights.
1566 /// \return the monodimensional histogram wrapped in a RResultPtr.
1567 ///
1568 /// This overload uses a default model histogram TH1D(name, title, 128u, 0., 0.).
1569 /// The "name" and "title" strings are built starting from the input column names.
1570 /// See the description of the first Histo1D() overload for more details.
1571 ///
1572 /// ### Example usage:
1573 /// ~~~{.cpp}
1574 /// // Deduce column types (this invocation needs jitting internally)
1575 /// auto myHist1 = myDf.Histo1D("myValue", "myweight");
1576 /// // Explicit column types
1577 /// auto myHist2 = myDf.Histo1D<float, int>("myValue", "myweight");
1578 /// ~~~
1579 template <typename V = RDFDetail::RInferredType, typename W = RDFDetail::RInferredType>
1580 RResultPtr<::TH1D> Histo1D(std::string_view vName, std::string_view wName)
1581 {
1582 // We build name and title based on the value and weight column names
1583 std::string str_vName{vName};
1584 std::string str_wName{wName};
1585 const auto h_name = str_vName + "_weighted_" + str_wName;
1586 const auto h_title = str_vName + ", weights: " + str_wName + ";" + str_vName + ";count * " + str_wName;
1587 return Histo1D<V, W>({h_name.c_str(), h_title.c_str(), 128u, 0., 0.}, vName, wName);
1588 }
1589
1590 ////////////////////////////////////////////////////////////////////////////
1591 /// \brief Fill and return a one-dimensional histogram with the weighted values of a column (*lazy action*).
1592 /// \tparam V The type of the column used to fill the histogram.
1593 /// \tparam W The type of the column used as weights.
1594 /// \param[in] model The returned histogram will be constructed using this as a model.
1595 /// \return the monodimensional histogram wrapped in a RResultPtr.
1596 ///
1597 /// This overload will use the first two default columns as column names.
1598 /// See the description of the first Histo1D() overload for more details.
1599 template <typename V, typename W>
1600 RResultPtr<::TH1D> Histo1D(const TH1DModel &model = {"", "", 128u, 0., 0.})
1601 {
1602 return Histo1D<V, W>(model, "", "");
1603 }
1604
1605 ////////////////////////////////////////////////////////////////////////////
1606 /// \brief Fill and return a two-dimensional histogram (*lazy action*).
1607 /// \tparam V1 The type of the column used to fill the x axis of the histogram.
1608 /// \tparam V2 The type of the column used to fill the y axis of the histogram.
1609 /// \param[in] model The returned histogram will be constructed using this as a model.
1610 /// \param[in] v1Name The name of the column that will fill the x axis.
1611 /// \param[in] v2Name The name of the column that will fill the y axis.
1612 /// \return the bidimensional histogram wrapped in a RResultPtr.
1613 ///
1614 /// Columns can be of a container type (e.g. std::vector<double>), in which case the histogram
1615 /// is filled with each one of the elements of the container. In case multiple columns of container type
1616 /// are provided (e.g. values and weights) they must have the same length for each one of the events (but
1617 /// possibly different lengths between events).
1618 /// This action is *lazy*: upon invocation of this method the calculation is
1619 /// booked but not executed. Also see RResultPtr.
1620 ///
1621 /// ### Example usage:
1622 /// ~~~{.cpp}
1623 /// // Deduce column types (this invocation needs jitting internally)
1624 /// auto myHist1 = myDf.Histo2D({"histName", "histTitle", 64u, 0., 128., 32u, -4., 4.}, "myValueX", "myValueY");
1625 /// // Explicit column types
1626 /// auto myHist2 = myDf.Histo2D<float, float>({"histName", "histTitle", 64u, 0., 128., 32u, -4., 4.}, "myValueX", "myValueY");
1627 /// ~~~
1628 ///
1629 ///
1630 /// \note Differently from other ROOT interfaces, the returned histogram is not associated to gDirectory
1631 /// and the caller is responsible for its lifetime (in particular, a typical source of confusion is that
1632 /// if result histograms go out of scope before the end of the program, ROOT might display a blank canvas).
1633 template <typename V1 = RDFDetail::RInferredType, typename V2 = RDFDetail::RInferredType>
1634 RResultPtr<::TH2D> Histo2D(const TH2DModel &model, std::string_view v1Name = "", std::string_view v2Name = "")
1635 {
1636 std::shared_ptr<::TH2D> h(nullptr);
1637 {
1638 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1639 h = model.GetHistogram();
1640 }
1641 if (!RDFInternal::HistoUtils<::TH2D>::HasAxisLimits(*h)) {
1642 throw std::runtime_error("2D histograms with no axes limits are not supported yet.");
1643 }
1644 const std::vector<std::string_view> columnViews = {v1Name, v2Name};
1645 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
1646 ? ColumnNames_t()
1647 : ColumnNames_t(columnViews.begin(), columnViews.end());
1648 return CreateAction<RDFInternal::ActionTags::Histo2D, V1, V2>(userColumns, h, h, fProxiedPtr);
1649 }
1650
1651 ////////////////////////////////////////////////////////////////////////////
1652 /// \brief Fill and return a weighted two-dimensional histogram (*lazy action*).
1653 /// \tparam V1 The type of the column used to fill the x axis of the histogram.
1654 /// \tparam V2 The type of the column used to fill the y axis of the histogram.
1655 /// \tparam W The type of the column used for the weights of the histogram.
1656 /// \param[in] model The returned histogram will be constructed using this as a model.
1657 /// \param[in] v1Name The name of the column that will fill the x axis.
1658 /// \param[in] v2Name The name of the column that will fill the y axis.
1659 /// \param[in] wName The name of the column that will provide the weights.
1660 /// \return the bidimensional histogram wrapped in a RResultPtr.
1661 ///
1662 /// This action is *lazy*: upon invocation of this method the calculation is
1663 /// booked but not executed. Also see RResultPtr.
1664 ///
1665 /// ### Example usage:
1666 /// ~~~{.cpp}
1667 /// // Deduce column types (this invocation needs jitting internally)
1668 /// auto myHist1 = myDf.Histo2D({"histName", "histTitle", 64u, 0., 128., 32u, -4., 4.}, "myValueX", "myValueY", "myWeight");
1669 /// // Explicit column types
1670 /// auto myHist2 = myDf.Histo2D<float, float, double>({"histName", "histTitle", 64u, 0., 128., 32u, -4., 4.}, "myValueX", "myValueY", "myWeight");
1671 /// ~~~
1672 ///
1673 /// See the documentation of the first Histo2D() overload for more details.
1674 template <typename V1 = RDFDetail::RInferredType, typename V2 = RDFDetail::RInferredType,
1675 typename W = RDFDetail::RInferredType>
1677 Histo2D(const TH2DModel &model, std::string_view v1Name, std::string_view v2Name, std::string_view wName)
1678 {
1679 std::shared_ptr<::TH2D> h(nullptr);
1680 {
1681 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1682 h = model.GetHistogram();
1683 }
1684 if (!RDFInternal::HistoUtils<::TH2D>::HasAxisLimits(*h)) {
1685 throw std::runtime_error("2D histograms with no axes limits are not supported yet.");
1686 }
1687 const std::vector<std::string_view> columnViews = {v1Name, v2Name, wName};
1688 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
1689 ? ColumnNames_t()
1690 : ColumnNames_t(columnViews.begin(), columnViews.end());
1691 return CreateAction<RDFInternal::ActionTags::Histo2D, V1, V2, W>(userColumns, h, h, fProxiedPtr);
1692 }
1693
1694 template <typename V1, typename V2, typename W>
1696 {
1697 return Histo2D<V1, V2, W>(model, "", "", "");
1698 }
1699
1700 ////////////////////////////////////////////////////////////////////////////
1701 /// \brief Fill and return a three-dimensional histogram (*lazy action*).
1702 /// \tparam V1 The type of the column used to fill the x axis of the histogram. Inferred if not present.
1703 /// \tparam V2 The type of the column used to fill the y axis of the histogram. Inferred if not present.
1704 /// \tparam V3 The type of the column used to fill the z axis of the histogram. Inferred if not present.
1705 /// \param[in] model The returned histogram will be constructed using this as a model.
1706 /// \param[in] v1Name The name of the column that will fill the x axis.
1707 /// \param[in] v2Name The name of the column that will fill the y axis.
1708 /// \param[in] v3Name The name of the column that will fill the z axis.
1709 /// \return the tridimensional histogram wrapped in a RResultPtr.
1710 ///
1711 /// This action is *lazy*: upon invocation of this method the calculation is
1712 /// booked but not executed. Also see RResultPtr.
1713 ///
1714 /// ### Example usage:
1715 /// ~~~{.cpp}
1716 /// // Deduce column types (this invocation needs jitting internally)
1717 /// auto myHist1 = myDf.Histo3D({"name", "title", 64u, 0., 128., 32u, -4., 4., 8u, -2., 2.},
1718 /// "myValueX", "myValueY", "myValueZ");
1719 /// // Explicit column types
1720 /// auto myHist2 = myDf.Histo3D<double, double, float>({"name", "title", 64u, 0., 128., 32u, -4., 4., 8u, -2., 2.},
1721 /// "myValueX", "myValueY", "myValueZ");
1722 /// ~~~
1723 /// \note If three-dimensional histograms consume too much memory in multithreaded runs, the cloning of TH3D
1724 /// per thread can be reduced using ROOT::RDF::Experimental::ThreadsPerTH3(). See the section "Memory Usage" in
1725 /// the RDataFrame description.
1726 /// \note Differently from other ROOT interfaces, the returned histogram is not associated to gDirectory
1727 /// and the caller is responsible for its lifetime (in particular, a typical source of confusion is that
1728 /// if result histograms go out of scope before the end of the program, ROOT might display a blank canvas).
1729 template <typename V1 = RDFDetail::RInferredType, typename V2 = RDFDetail::RInferredType,
1730 typename V3 = RDFDetail::RInferredType>
1731 RResultPtr<::TH3D> Histo3D(const TH3DModel &model, std::string_view v1Name = "", std::string_view v2Name = "",
1732 std::string_view v3Name = "")
1733 {
1734 std::shared_ptr<::TH3D> h(nullptr);
1735 {
1736 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1737 h = model.GetHistogram();
1738 }
1739 if (!RDFInternal::HistoUtils<::TH3D>::HasAxisLimits(*h)) {
1740 throw std::runtime_error("3D histograms with no axes limits are not supported yet.");
1741 }
1742 const std::vector<std::string_view> columnViews = {v1Name, v2Name, v3Name};
1743 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
1744 ? ColumnNames_t()
1745 : ColumnNames_t(columnViews.begin(), columnViews.end());
1746 return CreateAction<RDFInternal::ActionTags::Histo3D, V1, V2, V3>(userColumns, h, h, fProxiedPtr);
1747 }
1748
1749 ////////////////////////////////////////////////////////////////////////////
1750 /// \brief Fill and return a three-dimensional histogram (*lazy action*).
1751 /// \tparam V1 The type of the column used to fill the x axis of the histogram. Inferred if not present.
1752 /// \tparam V2 The type of the column used to fill the y axis of the histogram. Inferred if not present.
1753 /// \tparam V3 The type of the column used to fill the z axis of the histogram. Inferred if not present.
1754 /// \tparam W The type of the column used for the weights of the histogram. Inferred if not present.
1755 /// \param[in] model The returned histogram will be constructed using this as a model.
1756 /// \param[in] v1Name The name of the column that will fill the x axis.
1757 /// \param[in] v2Name The name of the column that will fill the y axis.
1758 /// \param[in] v3Name The name of the column that will fill the z axis.
1759 /// \param[in] wName The name of the column that will provide the weights.
1760 /// \return the tridimensional histogram wrapped in a RResultPtr.
1761 ///
1762 /// This action is *lazy*: upon invocation of this method the calculation is
1763 /// booked but not executed. Also see RResultPtr.
1764 ///
1765 /// ### Example usage:
1766 /// ~~~{.cpp}
1767 /// // Deduce column types (this invocation needs jitting internally)
1768 /// auto myHist1 = myDf.Histo3D({"name", "title", 64u, 0., 128., 32u, -4., 4., 8u, -2., 2.},
1769 /// "myValueX", "myValueY", "myValueZ", "myWeight");
1770 /// // Explicit column types
1771 /// using d_t = double;
1772 /// auto myHist2 = myDf.Histo3D<d_t, d_t, float, d_t>({"name", "title", 64u, 0., 128., 32u, -4., 4., 8u, -2., 2.},
1773 /// "myValueX", "myValueY", "myValueZ", "myWeight");
1774 /// ~~~
1775 ///
1776 ///
1777 /// See the documentation of the first Histo2D() overload for more details.
1778 template <typename V1 = RDFDetail::RInferredType, typename V2 = RDFDetail::RInferredType,
1779 typename V3 = RDFDetail::RInferredType, typename W = RDFDetail::RInferredType>
1780 RResultPtr<::TH3D> Histo3D(const TH3DModel &model, std::string_view v1Name, std::string_view v2Name,
1781 std::string_view v3Name, std::string_view wName)
1782 {
1783 std::shared_ptr<::TH3D> h(nullptr);
1784 {
1785 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1786 h = model.GetHistogram();
1787 }
1788 if (!RDFInternal::HistoUtils<::TH3D>::HasAxisLimits(*h)) {
1789 throw std::runtime_error("3D histograms with no axes limits are not supported yet.");
1790 }
1791 const std::vector<std::string_view> columnViews = {v1Name, v2Name, v3Name, wName};
1792 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
1793 ? ColumnNames_t()
1794 : ColumnNames_t(columnViews.begin(), columnViews.end());
1795 return CreateAction<RDFInternal::ActionTags::Histo3D, V1, V2, V3, W>(userColumns, h, h, fProxiedPtr);
1796 }
1797
1798 template <typename V1, typename V2, typename V3, typename W>
1800 {
1801 return Histo3D<V1, V2, V3, W>(model, "", "", "", "");
1802 }
1803
1804 ////////////////////////////////////////////////////////////////////////////
1805 /// \brief Fill and return an N-dimensional histogram (*lazy action*).
1806 /// \tparam FirstColumn The first type of the column the values of which are used to fill the object. Inferred if not
1807 /// present.
1808 /// \tparam OtherColumns A list of the other types of the columns the values of which are used to fill the
1809 /// object.
1810 /// \param[in] model The returned histogram will be constructed using this as a model.
1811 /// \param[in] columnList
1812 /// A list containing the names of the columns that will be passed when calling `Fill`.
1813 /// \param[in] wName The name of the column that will provide the weights.
1814 /// \return the N-dimensional histogram wrapped in a RResultPtr.
1815 ///
1816 /// This action is *lazy*: upon invocation of this method the calculation is
1817 /// booked but not executed. See RResultPtr documentation.
1818 ///
1819 /// ### Example usage:
1820 /// ~~~{.cpp}
1821 /// auto myFilledObj = myDf.HistoND<float, float, float, float>({"name","title", 4,
1822 /// {40,40,40,40}, {20.,20.,20.,20.}, {60.,60.,60.,60.}},
1823 /// {"col0", "col1", "col2", "col3"});
1824 /// ~~~
1825 ///
1826 /// \note A column with event weights should not be passed as part of `columnList`, but instead be passed in the new
1827 /// argument `wName`: `HistoND(model, cols, weightCol)`.
1828 ///
1829 template <typename FirstColumn, typename... OtherColumns> // need FirstColumn to disambiguate overloads
1830 RResultPtr<::THnD> HistoND(const THnDModel &model, const ColumnNames_t &columnList, std::string_view wName = "")
1831 {
1832 std::shared_ptr<::THnD> h(nullptr);
1833 {
1834 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1835 h = model.GetHistogram();
1836 const auto hDims = h->GetNdimensions();
1837 decltype(hDims) nCols = columnList.size();
1838
1839 if (!wName.empty() && nCols == hDims + 1)
1840 throw std::invalid_argument("The weight column was passed as an argument and at the same time the list of "
1841 "input columns contains one column more than the number of dimensions of the "
1842 "histogram. Call as 'HistoND(model, cols, weightCol)'.");
1843
1844 if (nCols == hDims + 1)
1845 Warning("HistoND", "Passing the column with the weights as the last column in the list is deprecated. "
1846 "Instead, pass it as a separate argument, e.g. 'HistoND(model, cols, weightCol)'.");
1847
1848 if (!wName.empty() || nCols == hDims + 1)
1849 h->Sumw2();
1850
1851 if (nCols != hDims + 1 && nCols != hDims)
1852 throw std::invalid_argument("Wrong number of columns for the specified number of histogram axes.");
1853 }
1854
1855 if (!wName.empty()) {
1856 // The action helper will invoke THnBase::Fill overload that performs weighted filling in case the number of
1857 // passed arguments is one more the number of dimensions of the histogram.
1858 ColumnNames_t userColumns = columnList;
1859 userColumns.push_back(std::string{wName});
1860 return CreateAction<RDFInternal::ActionTags::HistoND, FirstColumn, OtherColumns...>(userColumns, h, h,
1861 fProxiedPtr);
1862 }
1863 return CreateAction<RDFInternal::ActionTags::HistoND, FirstColumn, OtherColumns...>(columnList, h, h,
1864 fProxiedPtr);
1865 }
1866
1867 ////////////////////////////////////////////////////////////////////////////
1868 /// \brief Fill and return an N-dimensional histogram (*lazy action*).
1869 /// \param[in] model The returned histogram will be constructed using this as a model.
1870 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
1871 /// \param[in] wName The name of the column that will provide the weights.
1872 /// \return the N-dimensional histogram wrapped in a RResultPtr.
1873 ///
1874 /// This action is *lazy*: upon invocation of this method the calculation is
1875 /// booked but not executed. Also see RResultPtr.
1876 ///
1877 /// ### Example usage:
1878 /// ~~~{.cpp}
1879 /// auto myFilledObj = myDf.HistoND({"name","title", 4,
1880 /// {40,40,40,40}, {20.,20.,20.,20.}, {60.,60.,60.,60.}},
1881 /// {"col0", "col1", "col2", "col3"});
1882 /// ~~~
1883 ///
1884 /// \note A column with event weights should not be passed as part of `columnList`, but instead be passed in the new
1885 /// argument `wName`: `HistoND(model, cols, weightCol)`.
1886 ///
1887 RResultPtr<::THnD> HistoND(const THnDModel &model, const ColumnNames_t &columnList, std::string_view wName = "")
1888 {
1889 std::shared_ptr<::THnD> h(nullptr);
1890 {
1891 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1892 h = model.GetHistogram();
1893 const auto hDims = h->GetNdimensions();
1894 decltype(hDims) nCols = columnList.size();
1895
1896 if (!wName.empty() && nCols == hDims + 1)
1897 throw std::invalid_argument("The weight column was passed as an argument and at the same time the list of "
1898 "input columns contains one column more than the number of dimensions of the "
1899 "histogram. Call as 'HistoND(model, cols, weightCol)'.");
1900
1901 if (nCols == hDims + 1)
1902 Warning("HistoND", "Passing the column with the weights as the last column in the list is deprecated. "
1903 "Instead, pass it as a separate argument, e.g. 'HistoND(model, cols, weightCol)'.");
1904
1905 if (!wName.empty() || nCols == hDims + 1)
1906 h->Sumw2();
1907
1908 if (nCols != hDims + 1 && nCols != hDims)
1909 throw std::invalid_argument("Wrong number of columns for the specified number of histogram axes.");
1910 }
1911
1912 if (!wName.empty()) {
1913 // The action helper will invoke THnBase::Fill overload that performs weighted filling in case the number of
1914 // passed arguments is one more the number of dimensions of the histogram.
1915 ColumnNames_t userColumns = columnList;
1916 userColumns.push_back(std::string{wName});
1917 return CreateAction<RDFInternal::ActionTags::HistoND, RDFDetail::RInferredType>(userColumns, h, h, fProxiedPtr,
1918 userColumns.size());
1919 }
1920 return CreateAction<RDFInternal::ActionTags::HistoND, RDFDetail::RInferredType>(columnList, h, h, fProxiedPtr,
1921 columnList.size());
1922 }
1923
1924 ////////////////////////////////////////////////////////////////////////////
1925 /// \brief Fill and return a sparse N-dimensional histogram (*lazy action*).
1926 /// \tparam FirstColumn The first type of the column the values of which are used to fill the object. Inferred if not
1927 /// present.
1928 /// \tparam OtherColumns A list of the other types of the columns the values of which are used to fill the
1929 /// object.
1930 /// \param[in] model The returned histogram will be constructed using this as a model.
1931 /// \param[in] columnList
1932 /// A list containing the names of the columns that will be passed when calling `Fill`.
1933 /// \param[in] wName The name of the column that will provide the weights.
1934 /// \return the N-dimensional histogram wrapped in a RResultPtr.
1935 ///
1936 /// This action is *lazy*: upon invocation of this method the calculation is
1937 /// booked but not executed. See RResultPtr documentation.
1938 ///
1939 /// ### Example usage:
1940 /// ~~~{.cpp}
1941 /// auto myFilledObj = myDf.HistoNSparseD<float, float, float, float>({"name","title", 4,
1942 /// {40,40,40,40}, {20.,20.,20.,20.}, {60.,60.,60.,60.}},
1943 /// {"col0", "col1", "col2", "col3"});
1944 /// ~~~
1945 ///
1946 /// \note A column with event weights should not be passed as part of `columnList`, but instead be passed in the new
1947 /// argument `wName`: `HistoND(model, cols, weightCol)`.
1948 ///
1949 template <typename FirstColumn, typename... OtherColumns> // need FirstColumn to disambiguate overloads
1951 HistoNSparseD(const THnSparseDModel &model, const ColumnNames_t &columnList, std::string_view wName = "")
1952 {
1953 std::shared_ptr<::THnSparseD> h(nullptr);
1954 {
1955 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
1956 h = model.GetHistogram();
1957 const auto hDims = h->GetNdimensions();
1958 decltype(hDims) nCols = columnList.size();
1959
1960 if (!wName.empty() && nCols == hDims + 1)
1961 throw std::invalid_argument("The weight column was passed as an argument and at the same time the list of "
1962 "input columns contains one column more than the number of dimensions of the "
1963 "histogram. Call as 'HistoNSparseD(model, cols, weightCol)'.");
1964
1965 if (nCols == hDims + 1)
1966 Warning("HistoNSparseD",
1967 "Passing the column with the weights as the last column in the list is deprecated. "
1968 "Instead, pass it as a separate argument, e.g. 'HistoNSparseD(model, cols, weightCol)'.");
1969
1970 if (!wName.empty() || nCols == hDims + 1)
1971 h->Sumw2();
1972
1973 if (nCols != hDims + 1 && nCols != hDims)
1974 throw std::invalid_argument("Wrong number of columns for the specified number of histogram axes.");
1975 }
1976
1977 if (!wName.empty()) {
1978 // The action helper will invoke THnBase::Fill overload that performs weighted filling in case the number of
1979 // passed arguments is one more the number of dimensions of the histogram.
1980 ColumnNames_t userColumns = columnList;
1981 userColumns.push_back(std::string{wName});
1982 return CreateAction<RDFInternal::ActionTags::HistoNSparseD, FirstColumn, OtherColumns...>(userColumns, h, h,
1983 fProxiedPtr);
1984 }
1985 return CreateAction<RDFInternal::ActionTags::HistoNSparseD, FirstColumn, OtherColumns...>(columnList, h, h,
1986 fProxiedPtr);
1987 }
1988
1989 ////////////////////////////////////////////////////////////////////////////
1990 /// \brief Fill and return a sparse N-dimensional histogram (*lazy action*).
1991 /// \param[in] model The returned histogram will be constructed using this as a model.
1992 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
1993 /// \param[in] wName The name of the column that will provide the weights.
1994 /// \return the N-dimensional histogram wrapped in a RResultPtr.
1995 ///
1996 /// This action is *lazy*: upon invocation of this method the calculation is
1997 /// booked but not executed. Also see RResultPtr.
1998 ///
1999 /// ### Example usage:
2000 /// ~~~{.cpp}
2001 /// auto myFilledObj = myDf.HistoNSparseD({"name","title", 4,
2002 /// {40,40,40,40}, {20.,20.,20.,20.}, {60.,60.,60.,60.}},
2003 /// {"col0", "col1", "col2", "col3"});
2004 /// ~~~
2005 ///
2006 /// \note A column with event weights should not be passed as part of `columnList`, but instead be passed in the new
2007 /// argument `wName`: `HistoND(model, cols, weightCol)`.
2008 ///
2010 HistoNSparseD(const THnSparseDModel &model, const ColumnNames_t &columnList, std::string_view wName = "")
2011 {
2012 std::shared_ptr<::THnSparseD> h(nullptr);
2013 {
2014 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
2015 h = model.GetHistogram();
2016 const auto hDims = h->GetNdimensions();
2017 decltype(hDims) nCols = columnList.size();
2018
2019 if (!wName.empty() && nCols == hDims + 1)
2020 throw std::invalid_argument("The weight column was passed as an argument and at the same time the list of "
2021 "input columns contains one column more than the number of dimensions of the "
2022 "histogram. Call as 'HistoNSparseD(model, cols, weightCol)'.");
2023
2024 if (nCols == hDims + 1)
2025 Warning("HistoNSparseD",
2026 "Passing the column with the weights as the last column in the list is deprecated. "
2027 "Instead, pass it as a separate argument, e.g. 'HistoNSparseD(model, cols, weightCol)'.");
2028
2029 if (!wName.empty() || nCols == hDims + 1)
2030 h->Sumw2();
2031
2032 if (nCols != hDims + 1 && nCols != hDims)
2033 throw std::invalid_argument("Wrong number of columns for the specified number of histogram axes.");
2034 }
2035
2036 if (!wName.empty()) {
2037 // The action helper will invoke THnBase::Fill overload that performs weighted filling in case the number of
2038 // passed arguments is one more the number of dimensions of the histogram.
2039 ColumnNames_t userColumns = columnList;
2040 userColumns.push_back(std::string{wName});
2041 return CreateAction<RDFInternal::ActionTags::HistoNSparseD, RDFDetail::RInferredType>(
2042 userColumns, h, h, fProxiedPtr, userColumns.size());
2043 }
2044 return CreateAction<RDFInternal::ActionTags::HistoNSparseD, RDFDetail::RInferredType>(
2045 columnList, h, h, fProxiedPtr, columnList.size());
2046 }
2047
2048#ifdef R__HAS_ROOT7
2049 ////////////////////////////////////////////////////////////////////////////
2050 /// \brief Fill and return a one-dimensional RHist (*lazy action*).
2051 /// \tparam BinContentType The bin content type of the returned RHist.
2052 /// \param[in] nNormalBins The returned histogram will be constructed using this number of normal bins.
2053 /// \param[in] interval The axis interval of the constructed histogram (lower end inclusive, upper end exclusive).
2054 /// \param[in] vName The name of the column that will fill the histogram.
2055 /// \return the histogram wrapped in a RResultPtr.
2056 ///
2057 /// The column can be of a container type (e.g. `std::vector` or `RVec`), in which case the histogram is filled with
2058 /// each one of the elements of the container, and the container can also be nested.
2059 ///
2060 /// This action is *lazy*: upon invocation of this method the calculation is
2061 /// booked but not executed. Also see RResultPtr.
2062 ///
2063 /// ### Example usage:
2064 /// ~~~{.cpp}
2065 /// auto myHist = myDf.Hist(10, {5, 15}, "col0");
2066 /// ~~~
2067 template <typename BinContentType = double, typename V = RDFDetail::RInferredType>
2069 Hist(std::uint64_t nNormalBins, std::pair<double, double> interval, std::string_view vName)
2070 {
2071 std::shared_ptr h = std::make_shared<ROOT::Experimental::RHist<BinContentType>>(nNormalBins, interval);
2072
2073 const ColumnNames_t columnList = {std::string(vName)};
2074
2075 return Hist<V>(h, columnList);
2076 }
2077
2078 ////////////////////////////////////////////////////////////////////////////
2079 /// \brief Fill and return an RHist (*lazy action*).
2080 /// \tparam BinContentType The bin content type of the returned RHist.
2081 /// \param[in] axes The returned histogram will be constructed using these axes.
2082 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2083 /// \return the histogram wrapped in a RResultPtr.
2084 ///
2085 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the histogram is filled with
2086 /// each one of the elements of the container. In case multiple columns of container type are provided, they must
2087 /// have the same length for each event (but possibly different lengths between events). Containers can be nested,
2088 /// in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2089 ///
2090 /// This action is *lazy*: upon invocation of this method the calculation is
2091 /// booked but not executed. Also see RResultPtr.
2092 ///
2093 /// ### Example usage:
2094 /// ~~~{.cpp}
2095 /// ROOT::Experimental::RRegularAxis axis(10, {5.0, 15.0});
2096 /// auto myHist = myDf.Hist({axis}, {"col0"});
2097 /// ~~~
2098 template <typename BinContentType = double, typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes>
2100 Hist(std::vector<ROOT::Experimental::RAxisVariant> axes, const ColumnNames_t &columnList)
2101 {
2102 if (axes.size() != columnList.size()) {
2103 std::string msg = "Wrong number of columns for the specified number of histogram axes: ";
2104 msg += "expected " + std::to_string(axes.size()) + ", got " + std::to_string(columnList.size());
2105 throw std::invalid_argument(msg);
2106 }
2107
2108 std::shared_ptr h = std::make_shared<ROOT::Experimental::RHist<BinContentType>>(std::move(axes));
2109
2110 return Hist<ColumnType, ColumnTypes...>(h, columnList);
2111 }
2112
2113 ////////////////////////////////////////////////////////////////////////////
2114 /// \brief Fill the provided RHist (*lazy action*).
2115 /// \param[in] h The histogram that should be filled.
2116 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2117 /// \return the histogram wrapped in a RResultPtr.
2118 ///
2119 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the histogram is filled with
2120 /// each one of the elements of the container. In case multiple columns of container type are provided, they must
2121 /// have the same length for each event (but possibly different lengths between events). Containers can be nested,
2122 /// in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2123 ///
2124 /// This action is *lazy*: upon invocation of this method the calculation is
2125 /// booked but not executed. Also see RResultPtr.
2126 ///
2127 /// During execution of the computation graph, the passed histogram must only be accessed with methods that are
2128 /// allowed during concurrent filling.
2129 ///
2130 /// ### Example usage:
2131 /// ~~~{.cpp}
2132 /// auto h = std::make_shared<ROOT::Experimental::RHist<double>>(10, {5.0, 15.0});
2133 /// auto myHist = myDf.Hist(h, {"col0"});
2134 /// ~~~
2135 template <typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes, typename BinContentType>
2138 {
2140
2141 if (h->GetNDimensions() != columnList.size()) {
2142 std::string msg = "Wrong number of columns for the passed histogram: ";
2143 msg += "expected " + std::to_string(h->GetNDimensions()) + ", got " + std::to_string(columnList.size());
2144 throw std::invalid_argument(msg);
2145 }
2146
2147 return CreateAction<RDFInternal::ActionTags::Hist, ColumnType, ColumnTypes...>(columnList, h, h, fProxiedPtr,
2148 columnList.size());
2149 }
2150
2151 ////////////////////////////////////////////////////////////////////////////
2152 /// \brief Fill and return a one-dimensional RHist with weights (*lazy action*).
2153 /// \tparam BinContentType The bin content type of the returned RHist.
2154 /// \param[in] nNormalBins The returned histogram will be constructed using this number of normal bins.
2155 /// \param[in] interval The axis interval of the constructed histogram (lower end inclusive, upper end exclusive).
2156 /// \param[in] vName The name of the column that will fill the histogram.
2157 /// \param[in] wName The name of the column that will provide the weights.
2158 /// \return the histogram wrapped in a RResultPtr.
2159 ///
2160 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the histogram is filled with
2161 /// each one of the elements of the container. In case multiple columns of container type are provided, they must
2162 /// have the same length for each event (but possibly different lengths between events). Containers can be nested,
2163 /// in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2164 ///
2165 /// This action is *lazy*: upon invocation of this method the calculation is
2166 /// booked but not executed. Also see RResultPtr.
2167 ///
2168 /// ### Example usage:
2169 /// ~~~{.cpp}
2170 /// auto myHist = myDf.Hist(10, {5, 15}, "col0", "colW");
2171 /// ~~~
2172 template <typename BinContentType = ROOT::Experimental::RBinWithError, typename V = RDFDetail::RInferredType,
2173 typename W = RDFDetail::RInferredType>
2175 Hist(std::uint64_t nNormalBins, std::pair<double, double> interval, std::string_view vName, std::string_view wName)
2176 {
2177 std::shared_ptr h = std::make_shared<ROOT::Experimental::RHist<BinContentType>>(nNormalBins, interval);
2178
2179 const ColumnNames_t columnList = {std::string(vName)};
2180
2181 return Hist<V, W>(h, columnList, wName);
2182 }
2183
2184 ////////////////////////////////////////////////////////////////////////////
2185 /// \brief Fill and return an RHist with weights (*lazy action*).
2186 /// \tparam BinContentType The bin content type of the returned RHist.
2187 /// \param[in] axes The returned histogram will be constructed using these axes.
2188 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2189 /// \param[in] wName The name of the column that will provide the weights.
2190 /// \return the histogram wrapped in a RResultPtr.
2191 ///
2192 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the histogram is filled with
2193 /// each one of the elements of the container. In case multiple columns of container type are provided, they must
2194 /// have the same length for each event (but possibly different lengths between events). Containers can be nested,
2195 /// in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2196 ///
2197 /// This action is *lazy*: upon invocation of this method the calculation is
2198 /// booked but not executed. Also see RResultPtr.
2199 ///
2200 /// This overload is not available for integral bin content types (see \ref RHistEngine::SupportsWeightedFilling).
2201 ///
2202 /// ### Example usage:
2203 /// ~~~{.cpp}
2204 /// ROOT::Experimental::RRegularAxis axis(10, {5.0, 15.0});
2205 /// auto myHist = myDf.Hist({axis}, {"col0"}, "colW");
2206 /// ~~~
2207 template <typename BinContentType = ROOT::Experimental::RBinWithError,
2208 typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes>
2210 Hist(std::vector<ROOT::Experimental::RAxisVariant> axes, const ColumnNames_t &columnList, std::string_view wName)
2211 {
2213 "weighted filling is not supported for integral bin content types");
2214
2215 if (axes.size() != columnList.size()) {
2216 std::string msg = "Wrong number of columns for the specified number of histogram axes: ";
2217 msg += "expected " + std::to_string(axes.size()) + ", got " + std::to_string(columnList.size());
2218 throw std::invalid_argument(msg);
2219 }
2220
2221 std::shared_ptr h = std::make_shared<ROOT::Experimental::RHist<BinContentType>>(std::move(axes));
2222
2223 return Hist<ColumnType, ColumnTypes...>(h, columnList, wName);
2224 }
2225
2226 ////////////////////////////////////////////////////////////////////////////
2227 /// \brief Fill the provided RHist with weights (*lazy action*).
2228 /// \param[in] h The histogram that should be filled.
2229 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2230 /// \param[in] wName The name of the column that will provide the weights.
2231 /// \return the histogram wrapped in a RResultPtr.
2232 ///
2233 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the histogram is filled with
2234 /// each one of the elements of the container. In case multiple columns of container type are provided, they must
2235 /// have the same length for each event (but possibly different lengths between events). Containers can be nested,
2236 /// in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2237 ///
2238 /// This action is *lazy*: upon invocation of this method the calculation is
2239 /// booked but not executed. Also see RResultPtr.
2240 ///
2241 /// This overload is not available for integral bin content types (see \ref RHistEngine::SupportsWeightedFilling).
2242 ///
2243 /// During execution of the computation graph, the passed histogram must only be accessed with methods that are
2244 /// allowed during concurrent filling.
2245 ///
2246 /// ### Example usage:
2247 /// ~~~{.cpp}
2248 /// auto h = std::make_shared<ROOT::Experimental::RHist<double>>(10, {5.0, 15.0});
2249 /// auto myHist = myDf.Hist(h, {"col0"}, "colW");
2250 /// ~~~
2251 template <typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes, typename BinContentType>
2254 std::string_view wName)
2255 {
2257 "weighted filling is not supported for integral bin content types");
2258
2260
2261 if (h->GetNDimensions() != columnList.size()) {
2262 std::string msg = "Wrong number of columns for the passed histogram: ";
2263 msg += "expected " + std::to_string(h->GetNDimensions()) + ", got " + std::to_string(columnList.size());
2264 throw std::invalid_argument(msg);
2265 }
2266
2267 // Add the weight column to the list of argument columns to pass it through the infrastructure.
2268 ColumnNames_t columnListWithWeights(columnList);
2269 columnListWithWeights.push_back(std::string(wName));
2270
2271 return CreateAction<RDFInternal::ActionTags::HistWithWeight, ColumnType, ColumnTypes...>(
2272 columnListWithWeights, h, h, fProxiedPtr, columnListWithWeights.size());
2273 }
2274
2275 ////////////////////////////////////////////////////////////////////////////
2276 /// \brief Fill the provided RHistEngine (*lazy action*).
2277 /// \param[in] h The histogram that should be filled.
2278 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2279 /// \return the histogram wrapped in a RResultPtr.
2280 ///
2281 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the histogram is filled with
2282 /// each one of the elements of the container. In case multiple columns of container type are provided, they must
2283 /// have the same length for each event (but possibly different lengths between events). Containers can be nested,
2284 /// in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2285 ///
2286 /// This action is *lazy*: upon invocation of this method the calculation is
2287 /// booked but not executed. Also see RResultPtr.
2288 ///
2289 /// During execution of the computation graph, the passed histogram must only be accessed with methods that are
2290 /// allowed during concurrent filling.
2291 ///
2292 /// ### Example usage:
2293 /// ~~~{.cpp}
2294 /// auto h = std::make_shared<ROOT::Experimental::RHistEngine<double>>(10, {5.0, 15.0});
2295 /// auto myHist = myDf.Hist(h, {"col0"});
2296 /// ~~~
2297 template <typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes, typename BinContentType>
2300 {
2302
2303 if (h->GetNDimensions() != columnList.size()) {
2304 std::string msg = "Wrong number of columns for the passed histogram: ";
2305 msg += "expected " + std::to_string(h->GetNDimensions()) + ", got " + std::to_string(columnList.size());
2306 throw std::invalid_argument(msg);
2307 }
2308
2309 return CreateAction<RDFInternal::ActionTags::Hist, ColumnType, ColumnTypes...>(columnList, h, h, fProxiedPtr,
2310 columnList.size());
2311 }
2312
2313 ////////////////////////////////////////////////////////////////////////////
2314 /// \brief Fill the provided RHistEngine with weights (*lazy action*).
2315 /// \param[in] h The histogram that should be filled.
2316 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2317 /// \param[in] wName The name of the column that will provide the weights.
2318 /// \return the histogram wrapped in a RResultPtr.
2319 ///
2320 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the histogram is filled with
2321 /// each one of the elements of the container. In case multiple columns of container type are provided, they must
2322 /// have the same length for each event (but possibly different lengths between events). Containers can be nested,
2323 /// in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2324 ///
2325 /// This action is *lazy*: upon invocation of this method the calculation is
2326 /// booked but not executed. Also see RResultPtr.
2327 ///
2328 /// This overload is not available for integral bin content types (see \ref RHistEngine::SupportsWeightedFilling).
2329 ///
2330 /// During execution of the computation graph, the passed histogram must only be accessed with methods that are
2331 /// allowed during concurrent filling.
2332 ///
2333 /// ### Example usage:
2334 /// ~~~{.cpp}
2335 /// auto h = std::make_shared<ROOT::Experimental::RHistEngine<double>>(10, {5.0, 15.0});
2336 /// auto myHist = myDf.Hist(h, {"col0"}, "colW");
2337 /// ~~~
2338 template <typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes, typename BinContentType>
2341 std::string_view wName)
2342 {
2344 "weighted filling is not supported for integral bin content types");
2345
2347
2348 if (h->GetNDimensions() != columnList.size()) {
2349 std::string msg = "Wrong number of columns for the passed histogram: ";
2350 msg += "expected " + std::to_string(h->GetNDimensions()) + ", got " + std::to_string(columnList.size());
2351 throw std::invalid_argument(msg);
2352 }
2353
2354 // Add the weight column to the list of argument columns to pass it through the infrastructure.
2355 ColumnNames_t columnListWithWeights(columnList);
2356 columnListWithWeights.push_back(std::string(wName));
2357
2358 return CreateAction<RDFInternal::ActionTags::HistWithWeight, ColumnType, ColumnTypes...>(
2359 columnListWithWeights, h, h, fProxiedPtr, columnListWithWeights.size());
2360 }
2361
2362 ////////////////////////////////////////////////////////////////////////////
2363 /// \brief Fill and return a one-dimensional RProfile (*lazy action*).
2364 /// \param[in] nNormalBins The returned profile histogram will be constructed using this number of normal bins.
2365 /// \param[in] interval The axis interval of the constructed profile histogram (lower end inclusive, upper end
2366 /// exclusive).
2367 /// \param[in] xName The name of the column that will fill the profile histogram.
2368 /// \param[in] vName The name of the column that will provide the values for the profile histogram.
2369 /// \return the profile histogram wrapped in a RResultPtr.
2370 ///
2371 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the profile histogram is filled
2372 /// with each one of the elements of the container. In case multiple columns of container type are provided, they
2373 /// must have the same length for each event (but possibly different lengths between events). Containers can be
2374 /// nested, in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2375 ///
2376 /// This action is *lazy*: upon invocation of this method the calculation is
2377 /// booked but not executed. Also see RResultPtr.
2378 ///
2379 /// ### Example usage:
2380 /// ~~~{.cpp}
2381 /// auto myProfile = myDf.Profile(10, {5, 15}, "col0", "colV");
2382 /// ~~~
2383 template <typename X = RDFDetail::RInferredType, typename V = RDFDetail::RInferredType>
2384 RResultPtr<ROOT::Experimental::RProfile> Profile(std::uint64_t nNormalBins, std::pair<double, double> interval,
2385 std::string_view xName, std::string_view vName)
2386 {
2387 std::shared_ptr p = std::make_shared<ROOT::Experimental::RProfile>(nNormalBins, interval);
2388
2389 const ColumnNames_t columnList = {std::string(xName)};
2390
2391 return Profile<X, V>(p, columnList, vName);
2392 }
2393
2394 ////////////////////////////////////////////////////////////////////////////
2395 /// \brief Fill and return an RProfile (*lazy action*).
2396 /// \param[in] axes The returned profile histogram will be constructed using these axes.
2397 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2398 /// \param[in] vName The name of the column that will provide the values for the profile histogram.
2399 /// \return the profile histogram wrapped in a RResultPtr.
2400 ///
2401 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the profile histogram is filled
2402 /// with each one of the elements of the container. In case multiple columns of container type are provided, they
2403 /// must have the same length for each event (but possibly different lengths between events). Containers can be
2404 /// nested, in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2405 ///
2406 /// This action is *lazy*: upon invocation of this method the calculation is
2407 /// booked but not executed. Also see RResultPtr.
2408 ///
2409 /// ### Example usage:
2410 /// ~~~{.cpp}
2411 /// ROOT::Experimental::RRegularAxis axis(10, {5.0, 15.0});
2412 /// auto myProfile = myDf.Profile({axis}, {"col0"}, "colV");
2413 /// ~~~
2414 template <typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes>
2416 Profile(std::vector<ROOT::Experimental::RAxisVariant> axes, const ColumnNames_t &columnList, std::string_view vName)
2417 {
2418 if (axes.size() != columnList.size()) {
2419 std::string msg = "Wrong number of columns for the specified number of histogram axes: ";
2420 msg += "expected " + std::to_string(axes.size()) + ", got " + std::to_string(columnList.size());
2421 throw std::invalid_argument(msg);
2422 }
2423
2424 std::shared_ptr p = std::make_shared<ROOT::Experimental::RProfile>(std::move(axes));
2425
2426 return Profile<ColumnType, ColumnTypes...>(p, columnList, vName);
2427 }
2428
2429 ////////////////////////////////////////////////////////////////////////////
2430 /// \brief Fill the provided RProfile (*lazy action*).
2431 /// \param[in] p The profile histogram that should be filled.
2432 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2433 /// \param[in] vName The name of the column that will provide the values for the profile histogram.
2434 /// \return the profile histogram wrapped in a RResultPtr.
2435 ///
2436 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the profile histogram is filled
2437 /// with each one of the elements of the container. In case multiple columns of container type are provided, they
2438 /// must have the same length for each event (but possibly different lengths between events). Containers can be
2439 /// nested, in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2440 ///
2441 /// This action is *lazy*: upon invocation of this method the calculation is
2442 /// booked but not executed. Also see RResultPtr.
2443 ///
2444 /// During execution of the computation graph, the passed profile histogram must only be accessed with methods that
2445 /// are allowed during concurrent filling.
2446 ///
2447 /// ### Example usage:
2448 /// ~~~{.cpp}
2449 /// auto p = std::make_shared<ROOT::Experimental::RProfile>(10, {5.0, 15.0});
2450 /// auto myProfile = myDf.Profile(h, {"col0"}, "colV");
2451 /// ~~~
2452 template <typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes>
2454 Profile(std::shared_ptr<ROOT::Experimental::RProfile> p, const ColumnNames_t &columnList, std::string_view vName)
2455 {
2457
2458 if (p->GetNDimensions() != columnList.size()) {
2459 std::string msg = "Wrong number of columns for the passed profile histogram: ";
2460 msg += "expected " + std::to_string(p->GetNDimensions()) + ", got " + std::to_string(columnList.size());
2461 throw std::invalid_argument(msg);
2462 }
2463
2464 // Add the value column to the list of argument columns to pass it through the infrastructure.
2465 ColumnNames_t columnListWithValues(columnList);
2466 columnListWithValues.push_back(std::string(vName));
2467
2468 return CreateAction<RDFInternal::ActionTags::Profile, ColumnType, ColumnTypes...>(
2469 columnListWithValues, p, p, fProxiedPtr, columnListWithValues.size());
2470 }
2471
2472 ////////////////////////////////////////////////////////////////////////////
2473 /// \brief Fill and return a one-dimensional RProfile with weights (*lazy action*).
2474 /// \param[in] nNormalBins The returned profile histogram will be constructed using this number of normal bins.
2475 /// \param[in] interval The axis interval of the constructed profile histogram (lower end inclusive, upper end
2476 /// exclusive).
2477 /// \param[in] xName The name of the column that will fill the profile histogram.
2478 /// \param[in] vName The name of the column that will provide the values for the profile histogram.
2479 /// \param[in] wName The name of the column that will provide the weights.
2480 /// \return the profile histogram wrapped in a RResultPtr.
2481 ///
2482 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the profile histogram is filled
2483 /// with each one of the elements of the container. In case multiple columns of container type are provided, they
2484 /// must have the same length for each event (but possibly different lengths between events). Containers can be
2485 /// nested, in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2486 ///
2487 /// This action is *lazy*: upon invocation of this method the calculation is
2488 /// booked but not executed. Also see RResultPtr.
2489 ///
2490 /// ### Example usage:
2491 /// ~~~{.cpp}
2492 /// auto myProfile = myDf.Profile(10, {5, 15}, "col0", "colV", "colW");
2493 /// ~~~
2494 template <typename X = RDFDetail::RInferredType, typename V = RDFDetail::RInferredType,
2495 typename W = RDFDetail::RInferredType>
2497 Profile(std::uint64_t nNormalBins, std::pair<double, double> interval, std::string_view xName,
2498 std::string_view vName, std::string_view wName)
2499 {
2500 std::shared_ptr p = std::make_shared<ROOT::Experimental::RProfile>(nNormalBins, interval);
2501
2502 const ColumnNames_t columnList = {std::string(xName)};
2503
2504 return Profile<X, V, W>(p, columnList, vName, wName);
2505 }
2506
2507 ////////////////////////////////////////////////////////////////////////////
2508 /// \brief Fill and return an RProfile with weights (*lazy action*).
2509 /// \param[in] axes The returned profile histogram will be constructed using these axes.
2510 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2511 /// \param[in] vName The name of the column that will provide the values for the profile histogram.
2512 /// \param[in] wName The name of the column that will provide the weights.
2513 /// \return the profile histogram wrapped in a RResultPtr.
2514 ///
2515 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the profile histogram is filled
2516 /// with each one of the elements of the container. In case multiple columns of container type are provided, they
2517 /// must have the same length for each event (but possibly different lengths between events). Containers can be
2518 /// nested, in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2519 ///
2520 /// This action is *lazy*: upon invocation of this method the calculation is
2521 /// booked but not executed. Also see RResultPtr.
2522 ///
2523 /// ### Example usage:
2524 /// ~~~{.cpp}
2525 /// ROOT::Experimental::RRegularAxis axis(10, {5.0, 15.0});
2526 /// auto myProfile = myDf.Profile({axis}, {"col0"}, "colV", "colW");
2527 /// ~~~
2528 template <typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes>
2530 Profile(std::vector<ROOT::Experimental::RAxisVariant> axes, const ColumnNames_t &columnList, std::string_view vName,
2531 std::string_view wName)
2532 {
2533 if (axes.size() != columnList.size()) {
2534 std::string msg = "Wrong number of columns for the specified number of histogram axes: ";
2535 msg += "expected " + std::to_string(axes.size()) + ", got " + std::to_string(columnList.size());
2536 throw std::invalid_argument(msg);
2537 }
2538
2539 std::shared_ptr p = std::make_shared<ROOT::Experimental::RProfile>(std::move(axes));
2540
2541 return Profile<ColumnType, ColumnTypes...>(p, columnList, vName, wName);
2542 }
2543
2544 ////////////////////////////////////////////////////////////////////////////
2545 /// \brief Fill the provided RProfile with weights (*lazy action*).
2546 /// \param[in] p The profile histogram that should be filled.
2547 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2548 /// \param[in] vName The name of the column that will provide the values for the profile histogram.
2549 /// \param[in] wName The name of the column that will provide the weights.
2550 /// \return the profile histogram wrapped in a RResultPtr.
2551 ///
2552 /// Columns can be of a container type (e.g. `std::vector` or `RVec`), in which case the profile histogram is filled
2553 /// with each one of the elements of the container. In case multiple columns of container type are provided, they
2554 /// must have the same length for each event (but possibly different lengths between events). Containers can be
2555 /// nested, in which case their sizes must match recursively. Scalars are broadcasted to match container columns.
2556 ///
2557 /// This action is *lazy*: upon invocation of this method the calculation is
2558 /// booked but not executed. Also see RResultPtr.
2559 ///
2560 /// During execution of the computation graph, the passed profile histogram must only be accessed with methods that
2561 /// are allowed during concurrent filling.
2562 ///
2563 /// ### Example usage:
2564 /// ~~~{.cpp}
2565 /// auto h = std::make_shared<ROOT::Experimental::RPRofile>(10, {5.0, 15.0});
2566 /// auto myProfile = myDf.Profile(h, {"col0"}, "colV", "colW");
2567 /// ~~~
2568 template <typename ColumnType = RDFDetail::RInferredType, typename... ColumnTypes>
2570 Profile(std::shared_ptr<ROOT::Experimental::RProfile> p, const ColumnNames_t &columnList, std::string_view vName,
2571 std::string_view wName)
2572 {
2574
2575 if (p->GetNDimensions() != columnList.size()) {
2576 std::string msg = "Wrong number of columns for the passed profile histogram: ";
2577 msg += "expected " + std::to_string(p->GetNDimensions()) + ", got " + std::to_string(columnList.size());
2578 throw std::invalid_argument(msg);
2579 }
2580
2581 // Add the value and weight columns to the list of argument columns to pass it through the infrastructure.
2582 ColumnNames_t columnListWithValuesAndWeights(columnList);
2583 columnListWithValuesAndWeights.push_back(std::string(vName));
2584 columnListWithValuesAndWeights.push_back(std::string(wName));
2585
2586 return CreateAction<RDFInternal::ActionTags::ProfileWithWeight, ColumnType, ColumnTypes...>(
2587 columnListWithValuesAndWeights, p, p, fProxiedPtr, columnListWithValuesAndWeights.size());
2588 }
2589#endif
2590
2591 ////////////////////////////////////////////////////////////////////////////
2592 /// \brief Fill and return a TGraph object (*lazy action*).
2593 /// \tparam X The type of the column used to fill the x axis.
2594 /// \tparam Y The type of the column used to fill the y axis.
2595 /// \param[in] x The name of the column that will fill the x axis.
2596 /// \param[in] y The name of the column that will fill the y axis.
2597 /// \return the TGraph wrapped in a RResultPtr.
2598 ///
2599 /// Columns can be of a container type (e.g. std::vector<double>), in which case the TGraph
2600 /// is filled with each one of the elements of the container.
2601 /// If Multithreading is enabled, the order in which points are inserted is undefined.
2602 /// If the Graph has to be drawn, it is suggested to the user to sort it on the x before printing.
2603 /// A name and a title to the TGraph is given based on the input column names.
2604 ///
2605 /// This action is *lazy*: upon invocation of this method the calculation is
2606 /// booked but not executed. Also see RResultPtr.
2607 ///
2608 /// ### Example usage:
2609 /// ~~~{.cpp}
2610 /// // Deduce column types (this invocation needs jitting internally)
2611 /// auto myGraph1 = myDf.Graph("xValues", "yValues");
2612 /// // Explicit column types
2613 /// auto myGraph2 = myDf.Graph<int, float>("xValues", "yValues");
2614 /// ~~~
2615 ///
2616 /// \note Differently from other ROOT interfaces, the returned TGraph is not associated to gDirectory
2617 /// and the caller is responsible for its lifetime (in particular, a typical source of confusion is that
2618 /// if result histograms go out of scope before the end of the program, ROOT might display a blank canvas).
2619 template <typename X = RDFDetail::RInferredType, typename Y = RDFDetail::RInferredType>
2620 RResultPtr<::TGraph> Graph(std::string_view x = "", std::string_view y = "")
2621 {
2622 auto graph = std::make_shared<::TGraph>();
2623 const std::vector<std::string_view> columnViews = {x, y};
2624 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
2625 ? ColumnNames_t()
2626 : ColumnNames_t(columnViews.begin(), columnViews.end());
2627
2628 const auto validatedColumns = GetValidatedColumnNames(2, userColumns);
2629
2630 // We build a default name and title based on the input columns
2631 const auto g_name = validatedColumns[1] + "_vs_" + validatedColumns[0];
2632 const auto g_title = validatedColumns[1] + " vs " + validatedColumns[0];
2633 graph->SetNameTitle(g_name.c_str(), g_title.c_str());
2634 graph->GetXaxis()->SetTitle(validatedColumns[0].c_str());
2635 graph->GetYaxis()->SetTitle(validatedColumns[1].c_str());
2636
2637 return CreateAction<RDFInternal::ActionTags::Graph, X, Y>(validatedColumns, graph, graph, fProxiedPtr);
2638 }
2639
2640 ////////////////////////////////////////////////////////////////////////////
2641 /// \brief Fill and return a TGraphAsymmErrors object (*lazy action*).
2642 /// \param[in] x The name of the column that will fill the x axis.
2643 /// \param[in] y The name of the column that will fill the y axis.
2644 /// \param[in] exl The name of the column of X low errors
2645 /// \param[in] exh The name of the column of X high errors
2646 /// \param[in] eyl The name of the column of Y low errors
2647 /// \param[in] eyh The name of the column of Y high errors
2648 /// \return the TGraphAsymmErrors wrapped in a RResultPtr.
2649 ///
2650 /// Columns can be of a container type (e.g. std::vector<double>), in which case the graph
2651 /// is filled with each one of the elements of the container.
2652 /// If Multithreading is enabled, the order in which points are inserted is undefined.
2653 ///
2654 /// This action is *lazy*: upon invocation of this method the calculation is
2655 /// booked but not executed. Also see RResultPtr.
2656 ///
2657 /// ### Example usage:
2658 /// ~~~{.cpp}
2659 /// // Deduce column types (this invocation needs jitting internally)
2660 /// auto myGAE1 = myDf.GraphAsymmErrors("xValues", "yValues", "exl", "exh", "eyl", "eyh");
2661 /// // Explicit column types
2662 /// using f = float
2663 /// auto myGAE2 = myDf.GraphAsymmErrors<f, f, f, f, f, f>("xValues", "yValues", "exl", "exh", "eyl", "eyh");
2664 /// ~~~
2665 ///
2666 /// `GraphAsymmErrors` should also be used for the cases in which values associated only with
2667 /// one of the axes have associated errors. For example, only `ey` exist and `ex` are equal to zero.
2668 /// In such cases, user should do the following:
2669 /// ~~~{.cpp}
2670 /// // Create a column of zeros in RDataFrame
2671 /// auto rdf_withzeros = rdf.Define("zero", "0");
2672 /// // or alternatively:
2673 /// auto rdf_withzeros = rdf.Define("zero", []() -> double { return 0.;});
2674 /// // Create the graph with y errors only
2675 /// auto rdf_errorsOnYOnly = rdf_withzeros.GraphAsymmErrors("xValues", "yValues", "zero", "zero", "eyl", "eyh");
2676 /// ~~~
2677 ///
2678 /// \note Differently from other ROOT interfaces, the returned TGraphAsymmErrors is not associated to gDirectory
2679 /// and the caller is responsible for its lifetime (in particular, a typical source of confusion is that
2680 /// if result histograms go out of scope before the end of the program, ROOT might display a blank canvas).
2681 template <typename X = RDFDetail::RInferredType, typename Y = RDFDetail::RInferredType,
2682 typename EXL = RDFDetail::RInferredType, typename EXH = RDFDetail::RInferredType,
2683 typename EYL = RDFDetail::RInferredType, typename EYH = RDFDetail::RInferredType>
2685 GraphAsymmErrors(std::string_view x = "", std::string_view y = "", std::string_view exl = "",
2686 std::string_view exh = "", std::string_view eyl = "", std::string_view eyh = "")
2687 {
2688 auto graph = std::make_shared<::TGraphAsymmErrors>();
2689 const std::vector<std::string_view> columnViews = {x, y, exl, exh, eyl, eyh};
2690 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
2691 ? ColumnNames_t()
2692 : ColumnNames_t(columnViews.begin(), columnViews.end());
2693
2694 const auto validatedColumns = GetValidatedColumnNames(6, userColumns);
2695
2696 // We build a default name and title based on the input columns
2697 const auto g_name = validatedColumns[1] + "_vs_" + validatedColumns[0];
2698 const auto g_title = validatedColumns[1] + " vs " + validatedColumns[0];
2699 graph->SetNameTitle(g_name.c_str(), g_title.c_str());
2700 graph->GetXaxis()->SetTitle(validatedColumns[0].c_str());
2701 graph->GetYaxis()->SetTitle(validatedColumns[1].c_str());
2702
2703 return CreateAction<RDFInternal::ActionTags::GraphAsymmErrors, X, Y, EXL, EXH, EYL, EYH>(validatedColumns, graph,
2704 graph, fProxiedPtr);
2705 }
2706
2707 ////////////////////////////////////////////////////////////////////////////
2708 /// \brief Fill and return a one-dimensional profile (*lazy action*).
2709 /// \tparam V1 The type of the column the values of which are used to fill the profile. Inferred if not present.
2710 /// \tparam V2 The type of the column the values of which are used to fill the profile. Inferred if not present.
2711 /// \param[in] model The model to be considered to build the new return value.
2712 /// \param[in] v1Name The name of the column that will fill the x axis.
2713 /// \param[in] v2Name The name of the column that will fill the y axis.
2714 /// \return the monodimensional profile wrapped in a RResultPtr.
2715 ///
2716 /// This action is *lazy*: upon invocation of this method the calculation is
2717 /// booked but not executed. Also see RResultPtr.
2718 ///
2719 /// ### Example usage:
2720 /// ~~~{.cpp}
2721 /// // Deduce column types (this invocation needs jitting internally)
2722 /// auto myProf1 = myDf.Profile1D({"profName", "profTitle", 64u, -4., 4.}, "xValues", "yValues");
2723 /// // Explicit column types
2724 /// auto myProf2 = myDf.Graph<int, float>({"profName", "profTitle", 64u, -4., 4.}, "xValues", "yValues");
2725 /// ~~~
2726 ///
2727 /// \note Differently from other ROOT interfaces, the returned profile is not associated to gDirectory
2728 /// and the caller is responsible for its lifetime (in particular, a typical source of confusion is that
2729 /// if result histograms go out of scope before the end of the program, ROOT might display a blank canvas).
2730 template <typename V1 = RDFDetail::RInferredType, typename V2 = RDFDetail::RInferredType>
2732 Profile1D(const TProfile1DModel &model, std::string_view v1Name = "", std::string_view v2Name = "")
2733 {
2734 std::shared_ptr<::TProfile> h(nullptr);
2735 {
2736 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
2737 h = model.GetProfile();
2738 }
2739
2740 if (!RDFInternal::HistoUtils<::TProfile>::HasAxisLimits(*h)) {
2741 throw std::runtime_error("Profiles with no axes limits are not supported yet.");
2742 }
2743 const std::vector<std::string_view> columnViews = {v1Name, v2Name};
2744 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
2745 ? ColumnNames_t()
2746 : ColumnNames_t(columnViews.begin(), columnViews.end());
2747 return CreateAction<RDFInternal::ActionTags::Profile1D, V1, V2>(userColumns, h, h, fProxiedPtr);
2748 }
2749
2750 ////////////////////////////////////////////////////////////////////////////
2751 /// \brief Fill and return a one-dimensional profile (*lazy action*).
2752 /// \tparam V1 The type of the column the values of which are used to fill the profile. Inferred if not present.
2753 /// \tparam V2 The type of the column the values of which are used to fill the profile. Inferred if not present.
2754 /// \tparam W The type of the column the weights of which are used to fill the profile. Inferred if not present.
2755 /// \param[in] model The model to be considered to build the new return value.
2756 /// \param[in] v1Name The name of the column that will fill the x axis.
2757 /// \param[in] v2Name The name of the column that will fill the y axis.
2758 /// \param[in] wName The name of the column that will provide the weights.
2759 /// \return the monodimensional profile wrapped in a RResultPtr.
2760 ///
2761 /// This action is *lazy*: upon invocation of this method the calculation is
2762 /// booked but not executed. Also see RResultPtr.
2763 ///
2764 /// ### Example usage:
2765 /// ~~~{.cpp}
2766 /// // Deduce column types (this invocation needs jitting internally)
2767 /// auto myProf1 = myDf.Profile1D({"profName", "profTitle", 64u, -4., 4.}, "xValues", "yValues", "weight");
2768 /// // Explicit column types
2769 /// auto myProf2 = myDf.Profile1D<int, float, double>({"profName", "profTitle", 64u, -4., 4.},
2770 /// "xValues", "yValues", "weight");
2771 /// ~~~
2772 ///
2773 /// See the first Profile1D() overload for more details.
2774 template <typename V1 = RDFDetail::RInferredType, typename V2 = RDFDetail::RInferredType,
2775 typename W = RDFDetail::RInferredType>
2777 Profile1D(const TProfile1DModel &model, std::string_view v1Name, std::string_view v2Name, std::string_view wName)
2778 {
2779 std::shared_ptr<::TProfile> h(nullptr);
2780 {
2781 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
2782 h = model.GetProfile();
2783 }
2784
2785 if (!RDFInternal::HistoUtils<::TProfile>::HasAxisLimits(*h)) {
2786 throw std::runtime_error("Profile histograms with no axes limits are not supported yet.");
2787 }
2788 const std::vector<std::string_view> columnViews = {v1Name, v2Name, wName};
2789 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
2790 ? ColumnNames_t()
2791 : ColumnNames_t(columnViews.begin(), columnViews.end());
2792 return CreateAction<RDFInternal::ActionTags::Profile1D, V1, V2, W>(userColumns, h, h, fProxiedPtr);
2793 }
2794
2795 ////////////////////////////////////////////////////////////////////////////
2796 /// \brief Fill and return a one-dimensional profile (*lazy action*).
2797 /// See the first Profile1D() overload for more details.
2798 template <typename V1, typename V2, typename W>
2800 {
2801 return Profile1D<V1, V2, W>(model, "", "", "");
2802 }
2803
2804 ////////////////////////////////////////////////////////////////////////////
2805 /// \brief Fill and return a two-dimensional profile (*lazy action*).
2806 /// \tparam V1 The type of the column used to fill the x axis of the histogram. Inferred if not present.
2807 /// \tparam V2 The type of the column used to fill the y axis of the histogram. Inferred if not present.
2808 /// \tparam V3 The type of the column used to fill the z axis of the histogram. Inferred if not present.
2809 /// \param[in] model The returned profile will be constructed using this as a model.
2810 /// \param[in] v1Name The name of the column that will fill the x axis.
2811 /// \param[in] v2Name The name of the column that will fill the y axis.
2812 /// \param[in] v3Name The name of the column that will fill the z axis.
2813 /// \return the bidimensional profile wrapped in a RResultPtr.
2814 ///
2815 /// This action is *lazy*: upon invocation of this method the calculation is
2816 /// booked but not executed. Also see RResultPtr.
2817 ///
2818 /// ### Example usage:
2819 /// ~~~{.cpp}
2820 /// // Deduce column types (this invocation needs jitting internally)
2821 /// auto myProf1 = myDf.Profile2D({"profName", "profTitle", 40, -4, 4, 40, -4, 4, 0, 20},
2822 /// "xValues", "yValues", "zValues");
2823 /// // Explicit column types
2824 /// auto myProf2 = myDf.Profile2D<int, float, double>({"profName", "profTitle", 40, -4, 4, 40, -4, 4, 0, 20},
2825 /// "xValues", "yValues", "zValues");
2826 /// ~~~
2827 ///
2828 /// \note Differently from other ROOT interfaces, the returned profile is not associated to gDirectory
2829 /// and the caller is responsible for its lifetime (in particular, a typical source of confusion is that
2830 /// if result histograms go out of scope before the end of the program, ROOT might display a blank canvas).
2831 template <typename V1 = RDFDetail::RInferredType, typename V2 = RDFDetail::RInferredType,
2832 typename V3 = RDFDetail::RInferredType>
2833 RResultPtr<::TProfile2D> Profile2D(const TProfile2DModel &model, std::string_view v1Name = "",
2834 std::string_view v2Name = "", std::string_view v3Name = "")
2835 {
2836 std::shared_ptr<::TProfile2D> h(nullptr);
2837 {
2838 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
2839 h = model.GetProfile();
2840 }
2841
2842 if (!RDFInternal::HistoUtils<::TProfile2D>::HasAxisLimits(*h)) {
2843 throw std::runtime_error("2D profiles with no axes limits are not supported yet.");
2844 }
2845 const std::vector<std::string_view> columnViews = {v1Name, v2Name, v3Name};
2846 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
2847 ? ColumnNames_t()
2848 : ColumnNames_t(columnViews.begin(), columnViews.end());
2849 return CreateAction<RDFInternal::ActionTags::Profile2D, V1, V2, V3>(userColumns, h, h, fProxiedPtr);
2850 }
2851
2852 ////////////////////////////////////////////////////////////////////////////
2853 /// \brief Fill and return a two-dimensional profile (*lazy action*).
2854 /// \tparam V1 The type of the column used to fill the x axis of the histogram. Inferred if not present.
2855 /// \tparam V2 The type of the column used to fill the y axis of the histogram. Inferred if not present.
2856 /// \tparam V3 The type of the column used to fill the z axis of the histogram. Inferred if not present.
2857 /// \tparam W The type of the column used for the weights of the histogram. Inferred if not present.
2858 /// \param[in] model The returned histogram will be constructed using this as a model.
2859 /// \param[in] v1Name The name of the column that will fill the x axis.
2860 /// \param[in] v2Name The name of the column that will fill the y axis.
2861 /// \param[in] v3Name The name of the column that will fill the z axis.
2862 /// \param[in] wName The name of the column that will provide the weights.
2863 /// \return the bidimensional profile wrapped in a RResultPtr.
2864 ///
2865 /// This action is *lazy*: upon invocation of this method the calculation is
2866 /// booked but not executed. Also see RResultPtr.
2867 ///
2868 /// ### Example usage:
2869 /// ~~~{.cpp}
2870 /// // Deduce column types (this invocation needs jitting internally)
2871 /// auto myProf1 = myDf.Profile2D({"profName", "profTitle", 40, -4, 4, 40, -4, 4, 0, 20},
2872 /// "xValues", "yValues", "zValues", "weight");
2873 /// // Explicit column types
2874 /// auto myProf2 = myDf.Profile2D<int, float, double, int>({"profName", "profTitle", 40, -4, 4, 40, -4, 4, 0, 20},
2875 /// "xValues", "yValues", "zValues", "weight");
2876 /// ~~~
2877 ///
2878 /// See the first Profile2D() overload for more details.
2879 template <typename V1 = RDFDetail::RInferredType, typename V2 = RDFDetail::RInferredType,
2880 typename V3 = RDFDetail::RInferredType, typename W = RDFDetail::RInferredType>
2881 RResultPtr<::TProfile2D> Profile2D(const TProfile2DModel &model, std::string_view v1Name, std::string_view v2Name,
2882 std::string_view v3Name, std::string_view wName)
2883 {
2884 std::shared_ptr<::TProfile2D> h(nullptr);
2885 {
2886 ROOT::Internal::RDF::RIgnoreErrorLevelRAII iel(kError);
2887 h = model.GetProfile();
2888 }
2889
2890 if (!RDFInternal::HistoUtils<::TProfile2D>::HasAxisLimits(*h)) {
2891 throw std::runtime_error("2D profiles with no axes limits are not supported yet.");
2892 }
2893 const std::vector<std::string_view> columnViews = {v1Name, v2Name, v3Name, wName};
2894 const auto userColumns = RDFInternal::AtLeastOneEmptyString(columnViews)
2895 ? ColumnNames_t()
2896 : ColumnNames_t(columnViews.begin(), columnViews.end());
2897 return CreateAction<RDFInternal::ActionTags::Profile2D, V1, V2, V3, W>(userColumns, h, h, fProxiedPtr);
2898 }
2899
2900 /// \brief Fill and return a two-dimensional profile (*lazy action*).
2901 /// See the first Profile2D() overload for more details.
2902 template <typename V1, typename V2, typename V3, typename W>
2904 {
2905 return Profile2D<V1, V2, V3, W>(model, "", "", "", "");
2906 }
2907
2908 ////////////////////////////////////////////////////////////////////////////
2909 /// \brief Return an object of type T on which `T::Fill` will be called once per event (*lazy action*).
2910 ///
2911 /// Type T must provide at least:
2912 /// - a copy-constructor
2913 /// - a `Fill` method that accepts as many arguments and with same types as the column names passed as columnList
2914 /// (these types can also be passed as template parameters to this method)
2915 /// - a `Merge` method with signature `Merge(TCollection *)` or `Merge(const std::vector<T *>&)` that merges the
2916 /// objects passed as argument into the object on which `Merge` was called (an analogous of TH1::Merge). Note that
2917 /// if the signature that takes a `TCollection*` is used, then T must inherit from TObject (to allow insertion in
2918 /// the TCollection*).
2919 ///
2920 /// \tparam FirstColumn The first type of the column the values of which are used to fill the object. Inferred together with OtherColumns if not present.
2921 /// \tparam OtherColumns A list of the other types of the columns the values of which are used to fill the object.
2922 /// \tparam T The type of the object to fill. Automatically deduced.
2923 /// \param[in] model The model to be considered to build the new return value.
2924 /// \param[in] columnList A list containing the names of the columns that will be passed when calling `Fill`
2925 /// \return the filled object wrapped in a RResultPtr.
2926 ///
2927 /// The user gives up ownership of the model object.
2928 /// The list of column names to be used for filling must always be specified.
2929 /// This action is *lazy*: upon invocation of this method the calculation is booked but not executed.
2930 /// Also see RResultPtr.
2931 ///
2932 /// ### Example usage:
2933 /// ~~~{.cpp}
2934 /// MyClass obj;
2935 /// // Deduce column types (this invocation needs jitting internally, and in this case
2936 /// // MyClass needs to be known to the interpreter)
2937 /// auto myFilledObj = myDf.Fill(obj, {"col0", "col1"});
2938 /// // explicit column types
2939 /// auto myFilledObj = myDf.Fill<float, float>(obj, {"col0", "col1"});
2940 /// ~~~
2941 ///
2942 template <typename FirstColumn = RDFDetail::RInferredType, typename... OtherColumns, typename T>
2943 RResultPtr<std::decay_t<T>> Fill(T &&model, const ColumnNames_t &columnList)
2944 {
2945 auto h = std::make_shared<std::decay_t<T>>(std::forward<T>(model));
2946 if (!RDFInternal::HistoUtils<T>::HasAxisLimits(*h)) {
2947 throw std::runtime_error("The absence of axes limits is not supported yet.");
2948 }
2949 return CreateAction<RDFInternal::ActionTags::Fill, FirstColumn, OtherColumns...>(columnList, h, h, fProxiedPtr,
2950 columnList.size());
2951 }
2952
2953 ////////////////////////////////////////////////////////////////////////////
2954 /// \brief Return a TStatistic object, filled once per event (*lazy action*).
2955 ///
2956 /// \tparam V The type of the value column
2957 /// \param[in] value The name of the column with the values to fill the statistics with.
2958 /// \return the filled TStatistic object wrapped in a RResultPtr.
2959 ///
2960 /// ### Example usage:
2961 /// ~~~{.cpp}
2962 /// // Deduce column type (this invocation needs jitting internally)
2963 /// auto stats0 = myDf.Stats("values");
2964 /// // Explicit column type
2965 /// auto stats1 = myDf.Stats<float>("values");
2966 /// ~~~
2967 ///
2968 template <typename V = RDFDetail::RInferredType>
2969 RResultPtr<TStatistic> Stats(std::string_view value = "")
2970 {
2971 ColumnNames_t columns;
2972 if (!value.empty()) {
2973 columns.emplace_back(std::string(value));
2974 }
2975 const auto validColumnNames = GetValidatedColumnNames(1, columns);
2976 if (std::is_same<V, RDFDetail::RInferredType>::value) {
2977 return Fill(TStatistic(), validColumnNames);
2978 } else {
2979 return Fill<V>(TStatistic(), validColumnNames);
2980 }
2981 }
2982
2983 ////////////////////////////////////////////////////////////////////////////
2984 /// \brief Return a TStatistic object, filled once per event (*lazy action*).
2985 ///
2986 /// \tparam V The type of the value column
2987 /// \tparam W The type of the weight column
2988 /// \param[in] value The name of the column with the values to fill the statistics with.
2989 /// \param[in] weight The name of the column with the weights to fill the statistics with.
2990 /// \return the filled TStatistic object wrapped in a RResultPtr.
2991 ///
2992 /// ### Example usage:
2993 /// ~~~{.cpp}
2994 /// // Deduce column types (this invocation needs jitting internally)
2995 /// auto stats0 = myDf.Stats("values", "weights");
2996 /// // Explicit column types
2997 /// auto stats1 = myDf.Stats<int, float>("values", "weights");
2998 /// ~~~
2999 ///
3000 template <typename V = RDFDetail::RInferredType, typename W = RDFDetail::RInferredType>
3001 RResultPtr<TStatistic> Stats(std::string_view value, std::string_view weight)
3002 {
3003 ColumnNames_t columns{std::string(value), std::string(weight)};
3004 constexpr auto vIsInferred = std::is_same<V, RDFDetail::RInferredType>::value;
3005 constexpr auto wIsInferred = std::is_same<W, RDFDetail::RInferredType>::value;
3006 const auto validColumnNames = GetValidatedColumnNames(2, columns);
3007 // We have 3 cases:
3008 // 1. Both types are inferred: we use Fill and let the jit kick in.
3009 // 2. One of the two types is explicit and the other one is inferred: the case is not supported.
3010 // 3. Both types are explicit: we invoke the fully compiled Fill method.
3011 if (vIsInferred && wIsInferred) {
3012 return Fill(TStatistic(), validColumnNames);
3013 } else if (vIsInferred != wIsInferred) {
3014 std::string error("The ");
3015 error += vIsInferred ? "value " : "weight ";
3016 error += "column type is explicit, while the ";
3017 error += vIsInferred ? "weight " : "value ";
3018 error += " is specified to be inferred. This case is not supported: please specify both types or none.";
3019 throw std::runtime_error(error);
3020 } else {
3021 return Fill<V, W>(TStatistic(), validColumnNames);
3022 }
3023 }
3024
3025 ////////////////////////////////////////////////////////////////////////////
3026 /// \brief Return the minimum of processed column values (*lazy action*).
3027 /// \tparam T The type of the branch/column.
3028 /// \param[in] columnName The name of the branch/column to be treated.
3029 /// \return the minimum value of the selected column wrapped in a RResultPtr.
3030 ///
3031 /// If T is not specified, RDataFrame will infer it from the data and just-in-time compile the correct
3032 /// template specialization of this method.
3033 /// If the type of the column is inferred, the return type is `double`, the type of the column otherwise.
3034 ///
3035 /// This action is *lazy*: upon invocation of this method the calculation is
3036 /// booked but not executed. Also see RResultPtr.
3037 ///
3038 /// ### Example usage:
3039 /// ~~~{.cpp}
3040 /// // Deduce column type (this invocation needs jitting internally)
3041 /// auto minVal0 = myDf.Min("values");
3042 /// // Explicit column type
3043 /// auto minVal1 = myDf.Min<double>("values");
3044 /// ~~~
3045 ///
3046 template <typename T = RDFDetail::RInferredType>
3047 RResultPtr<RDFDetail::MinReturnType_t<T>> Min(std::string_view columnName = "")
3048 {
3049 const auto userColumns = columnName.empty() ? ColumnNames_t() : ColumnNames_t({std::string(columnName)});
3050 using RetType_t = RDFDetail::MinReturnType_t<T>;
3051 auto minV = std::make_shared<RetType_t>(std::numeric_limits<RetType_t>::max());
3052 return CreateAction<RDFInternal::ActionTags::Min, T>(userColumns, minV, minV, fProxiedPtr);
3053 }
3054
3055 ////////////////////////////////////////////////////////////////////////////
3056 /// \brief Return the maximum of processed column values (*lazy action*).
3057 /// \tparam T The type of the branch/column.
3058 /// \param[in] columnName The name of the branch/column to be treated.
3059 /// \return the maximum value of the selected column wrapped in a RResultPtr.
3060 ///
3061 /// If T is not specified, RDataFrame will infer it from the data and just-in-time compile the correct
3062 /// template specialization of this method.
3063 /// If the type of the column is inferred, the return type is `double`, the type of the column otherwise.
3064 ///
3065 /// This action is *lazy*: upon invocation of this method the calculation is
3066 /// booked but not executed. Also see RResultPtr.
3067 ///
3068 /// ### Example usage:
3069 /// ~~~{.cpp}
3070 /// // Deduce column type (this invocation needs jitting internally)
3071 /// auto maxVal0 = myDf.Max("values");
3072 /// // Explicit column type
3073 /// auto maxVal1 = myDf.Max<double>("values");
3074 /// ~~~
3075 ///
3076 template <typename T = RDFDetail::RInferredType>
3077 RResultPtr<RDFDetail::MaxReturnType_t<T>> Max(std::string_view columnName = "")
3078 {
3079 const auto userColumns = columnName.empty() ? ColumnNames_t() : ColumnNames_t({std::string(columnName)});
3080 using RetType_t = RDFDetail::MaxReturnType_t<T>;
3081 auto maxV = std::make_shared<RetType_t>(std::numeric_limits<RetType_t>::lowest());
3082 return CreateAction<RDFInternal::ActionTags::Max, T>(userColumns, maxV, maxV, fProxiedPtr);
3083 }
3084
3085 ////////////////////////////////////////////////////////////////////////////
3086 /// \brief Return the mean of processed column values (*lazy action*).
3087 /// \tparam T The type of the branch/column.
3088 /// \param[in] columnName The name of the branch/column to be treated.
3089 /// \return the mean value of the selected column wrapped in a RResultPtr.
3090 ///
3091 /// If T is not specified, RDataFrame will infer it from the data and just-in-time compile the correct
3092 /// template specialization of this method.
3093 /// Note that internally, the summations are executed with Kahan sums in double precision, irrespective
3094 /// of the type of column that is read.
3095 ///
3096 /// This action is *lazy*: upon invocation of this method the calculation is
3097 /// booked but not executed. Also see RResultPtr.
3098 ///
3099 /// ### Example usage:
3100 /// ~~~{.cpp}
3101 /// // Deduce column type (this invocation needs jitting internally)
3102 /// auto meanVal0 = myDf.Mean("values");
3103 /// // Explicit column type
3104 /// auto meanVal1 = myDf.Mean<double>("values");
3105 /// ~~~
3106 ///
3107 template <typename T = RDFDetail::RInferredType>
3108 RResultPtr<double> Mean(std::string_view columnName = "")
3109 {
3110 const auto userColumns = columnName.empty() ? ColumnNames_t() : ColumnNames_t({std::string(columnName)});
3111 auto meanV = std::make_shared<double>(0);
3112 return CreateAction<RDFInternal::ActionTags::Mean, T>(userColumns, meanV, meanV, fProxiedPtr);
3113 }
3114
3115 ////////////////////////////////////////////////////////////////////////////
3116 /// \brief Return the unbiased standard deviation of processed column values (*lazy action*).
3117 /// \tparam T The type of the branch/column.
3118 /// \param[in] columnName The name of the branch/column to be treated.
3119 /// \return the standard deviation value of the selected column wrapped in a RResultPtr.
3120 ///
3121 /// If T is not specified, RDataFrame will infer it from the data and just-in-time compile the correct
3122 /// template specialization of this method.
3123 ///
3124 /// This action is *lazy*: upon invocation of this method the calculation is
3125 /// booked but not executed. Also see RResultPtr.
3126 ///
3127 /// ### Example usage:
3128 /// ~~~{.cpp}
3129 /// // Deduce column type (this invocation needs jitting internally)
3130 /// auto stdDev0 = myDf.StdDev("values");
3131 /// // Explicit column type
3132 /// auto stdDev1 = myDf.StdDev<double>("values");
3133 /// ~~~
3134 ///
3135 template <typename T = RDFDetail::RInferredType>
3136 RResultPtr<double> StdDev(std::string_view columnName = "")
3137 {
3138 const auto userColumns = columnName.empty() ? ColumnNames_t() : ColumnNames_t({std::string(columnName)});
3139 auto stdDeviationV = std::make_shared<double>(0);
3140 return CreateAction<RDFInternal::ActionTags::StdDev, T>(userColumns, stdDeviationV, stdDeviationV, fProxiedPtr);
3141 }
3142
3143 ////////////////////////////////////////////////////////////////////////////
3144 /// \brief Return the median value of the input column (*lazy action*).
3145 /// \tparam T The type of the column.
3146 /// \param[in] columnName The name of the column to be treated.
3147 /// \return The median value of the selected column wrapped in a RResultPtr.
3148 ///
3149 /// If T is not specified, RDataFrame will infer it from the data and just-in-time compile the correct
3150 /// template specialization of this method.
3151 /// The result is always a double, irrespective of the type of column that is read. For an even
3152 /// number of entries, the median is the average of the two middle values.
3153 ///
3154 /// \note If the column is empty, a signaling NaN is returned.
3155 ///
3156 /// \note Computing the exact median requires all column values to be held in memory at once, so the
3157 /// memory used by this action grows with the number of processed entries. Consider this when running
3158 /// over large datasets.
3159 ///
3160 /// This action is *lazy*: upon invocation of this method the calculation is
3161 /// booked but not executed. Also see RResultPtr.
3162 ///
3163 /// ### Example usage:
3164 /// ~~~{.cpp}
3165 /// // Deduce column type (this invocation needs jitting internally)
3166 /// auto medianVal0 = myDf.Median("values");
3167 /// // Explicit column type
3168 /// auto medianVal1 = myDf.Median<double>("values");
3169 /// ~~~
3170 ///
3171 template <typename T = RDFDetail::RInferredType>
3172 RResultPtr<double> Median(std::string_view columnName = "")
3173 {
3174 const auto userColumns = columnName.empty() ? ColumnNames_t() : ColumnNames_t({std::string(columnName)});
3175 auto medianV = std::make_shared<double>(0);
3176 return CreateAction<RDFInternal::ActionTags::Median, T>(userColumns, medianV, medianV, fProxiedPtr);
3177 }
3178
3179 // clang-format off
3180 ////////////////////////////////////////////////////////////////////////////
3181 /// \brief Return the sum of processed column values (*lazy action*).
3182 /// \tparam T The type of the branch/column.
3183 /// \param[in] columnName The name of the branch/column.
3184 /// \param[in] initValue Optional initial value for the sum. If not present, the column values must be default-constructible.
3185 /// \return the sum of the selected column wrapped in a RResultPtr.
3186 ///
3187 /// If T is not specified, RDataFrame will infer it from the data and just-in-time compile the correct
3188 /// template specialization of this method.
3189 /// If the type of the column is inferred, the return type is `double`, the type of the column otherwise.
3190 ///
3191 /// This action is *lazy*: upon invocation of this method the calculation is
3192 /// booked but not executed. Also see RResultPtr.
3193 ///
3194 /// ### Example usage:
3195 /// ~~~{.cpp}
3196 /// // Deduce column type (this invocation needs jitting internally)
3197 /// auto sum0 = myDf.Sum("values");
3198 /// // Explicit column type
3199 /// auto sum1 = myDf.Sum<double>("values");
3200 /// ~~~
3201 ///
3202 template <typename T = RDFDetail::RInferredType>
3204 Sum(std::string_view columnName = "",
3205 const RDFDetail::SumReturnType_t<T> &initValue = RDFDetail::SumReturnType_t<T>{})
3206 {
3207 const auto userColumns = columnName.empty() ? ColumnNames_t() : ColumnNames_t({std::string(columnName)});
3208 auto sumV = std::make_shared<RDFDetail::SumReturnType_t<T>>(initValue);
3209 return CreateAction<RDFInternal::ActionTags::Sum, T>(userColumns, sumV, sumV, fProxiedPtr);
3210 }
3211 // clang-format on
3212
3213 ////////////////////////////////////////////////////////////////////////////
3214 /// \brief Gather filtering statistics.
3215 /// \return the resulting `RCutFlowReport` instance wrapped in a RResultPtr.
3216 ///
3217 /// Calling `Report` on the main `RDataFrame` object gathers stats for
3218 /// all named filters in the call graph. Calling this method on a
3219 /// stored chain state (i.e. a graph node different from the first) gathers
3220 /// the stats for all named filters in the chain section between the original
3221 /// `RDataFrame` and that node (included). Stats are gathered in the same
3222 /// order as the named filters have been added to the graph.
3223 /// A RResultPtr<RCutFlowReport> is returned to allow inspection of the
3224 /// effects cuts had.
3225 ///
3226 /// This action is *lazy*: upon invocation of
3227 /// this method the calculation is booked but not executed. See RResultPtr
3228 /// documentation.
3229 ///
3230 /// ### Example usage:
3231 /// ~~~{.cpp}
3232 /// auto filtered = d.Filter(cut1, {"b1"}, "Cut1").Filter(cut2, {"b2"}, "Cut2");
3233 /// auto cutReport = filtered3.Report();
3234 /// cutReport->Print();
3235 /// ~~~
3236 ///
3238 {
3239 bool returnEmptyReport = false;
3240 // if this is a RInterface<RLoopManager> on which `Define` has been called, users
3241 // are calling `Report` on a chain of the form LoopManager->Define->Define->..., which
3242 // certainly does not contain named filters.
3243 // The number 4 takes into account the implicit columns for entry and slot number
3244 // and their aliases (2 + 2, i.e. {r,t}dfentry_ and {r,t}dfslot_)
3245 if (std::is_same<Proxied, RLoopManager>::value && fColRegister.GenerateColumnNames().size() > 4)
3246 returnEmptyReport = true;
3247
3248 auto rep = std::make_shared<RCutFlowReport>();
3249 using Helper_t = RDFInternal::ReportHelper<Proxied>;
3251
3252 auto action = std::make_unique<Action_t>(Helper_t(rep, fProxiedPtr.get(), returnEmptyReport), ColumnNames_t({}),
3254
3255 return MakeResultPtr(rep, *fLoopManager, std::move(action));
3256 }
3257
3258
3259 ////////////////////////////////////////////////////////////////////////////
3260 /// \brief Provides a representation of the columns in the dataset.
3261 /// \tparam ColumnTypes variadic list of branch/column types.
3262 /// \param[in] columnList Names of the columns to be displayed.
3263 /// \param[in] nRows Number of events for each column to be displayed.
3264 /// \param[in] nMaxCollectionElements Maximum number of collection elements to display per row.
3265 /// \return the `RDisplay` instance wrapped in a RResultPtr.
3266 ///
3267 /// This function returns a `RResultPtr<RDisplay>` containing all the entries to be displayed, organized in a tabular
3268 /// form. RDisplay will either print on the standard output a summarized version through `RDisplay::Print()` or will
3269 /// return a complete version through `RDisplay::AsString()`.
3270 ///
3271 /// This action is *lazy*: upon invocation of this method the calculation is booked but not executed. Also see
3272 /// RResultPtr.
3273 ///
3274 /// Example usage:
3275 /// ~~~{.cpp}
3276 /// // Preparing the RResultPtr<RDisplay> object with all columns and default number of entries
3277 /// auto d1 = rdf.Display("");
3278 /// // Preparing the RResultPtr<RDisplay> object with two columns and 128 entries
3279 /// auto d2 = d.Display({"x", "y"}, 128);
3280 /// // Printing the short representations, the event loop will run
3281 /// d1->Print();
3282 /// d2->Print();
3283 /// ~~~
3284 template <typename... ColumnTypes>
3285 RResultPtr<RDisplay> Display(const ColumnNames_t &columnList, size_t nRows = 5, size_t nMaxCollectionElements = 10)
3286 {
3287 CheckIMTDisabled("Display");
3288 auto newCols = columnList;
3289 newCols.insert(newCols.begin(), "rdfentry_"); // Artificially insert first column
3290 auto displayer = std::make_shared<RDisplay>(newCols, GetColumnTypeNamesList(newCols), nMaxCollectionElements);
3291 using displayHelperArgs_t = std::pair<size_t, std::shared_ptr<RDisplay>>;
3292 // Need to add ULong64_t type corresponding to the first column rdfentry_
3293 return CreateAction<RDFInternal::ActionTags::Display, ULong64_t, ColumnTypes...>(
3294 std::move(newCols), displayer, std::make_shared<displayHelperArgs_t>(nRows, displayer), fProxiedPtr);
3295 }
3296
3297 ////////////////////////////////////////////////////////////////////////////
3298 /// \brief Provides a representation of the columns in the dataset.
3299 /// \param[in] columnList Names of the columns to be displayed.
3300 /// \param[in] nRows Number of events for each column to be displayed.
3301 /// \param[in] nMaxCollectionElements Maximum number of collection elements to display per row.
3302 /// \return the `RDisplay` instance wrapped in a RResultPtr.
3303 ///
3304 /// This overload automatically infers the column types.
3305 /// See the previous overloads for further details.
3306 ///
3307 /// Invoked when no types are specified to Display
3308 RResultPtr<RDisplay> Display(const ColumnNames_t &columnList, size_t nRows = 5, size_t nMaxCollectionElements = 10)
3309 {
3310 CheckIMTDisabled("Display");
3311 auto newCols = columnList;
3312 newCols.insert(newCols.begin(), "rdfentry_"); // Artificially insert first column
3313 auto displayer = std::make_shared<RDisplay>(newCols, GetColumnTypeNamesList(newCols), nMaxCollectionElements);
3314 using displayHelperArgs_t = std::pair<size_t, std::shared_ptr<RDisplay>>;
3315 return CreateAction<RDFInternal::ActionTags::Display, RDFDetail::RInferredType>(
3316 std::move(newCols), displayer, std::make_shared<displayHelperArgs_t>(nRows, displayer), fProxiedPtr,
3317 columnList.size() + 1);
3318 }
3319
3320 ////////////////////////////////////////////////////////////////////////////
3321 /// \brief Provides a representation of the columns in the dataset.
3322 /// \param[in] columnNameRegexp A regular expression to select the columns.
3323 /// \param[in] nRows Number of events for each column to be displayed.
3324 /// \param[in] nMaxCollectionElements Maximum number of collection elements to display per row.
3325 /// \return the `RDisplay` instance wrapped in a RResultPtr.
3326 ///
3327 /// The existing columns are matched against the regular expression. If the string provided
3328 /// is empty, all columns are selected.
3329 /// See the previous overloads for further details.
3331 Display(std::string_view columnNameRegexp = "", size_t nRows = 5, size_t nMaxCollectionElements = 10)
3332 {
3333 const auto columnNames = GetColumnNames();
3334 const auto selectedColumns = RDFInternal::ConvertRegexToColumns(columnNames, columnNameRegexp, "Display");
3335 return Display(selectedColumns, nRows, nMaxCollectionElements);
3336 }
3337
3338 ////////////////////////////////////////////////////////////////////////////
3339 /// \brief Provides a representation of the columns in the dataset.
3340 /// \param[in] columnList Names of the columns to be displayed.
3341 /// \param[in] nRows Number of events for each column to be displayed.
3342 /// \param[in] nMaxCollectionElements Number of maximum elements in collection.
3343 /// \return the `RDisplay` instance wrapped in a RResultPtr.
3344 ///
3345 /// See the previous overloads for further details.
3347 Display(std::initializer_list<std::string> columnList, size_t nRows = 5, size_t nMaxCollectionElements = 10)
3348 {
3349 ColumnNames_t selectedColumns(columnList);
3350 return Display(selectedColumns, nRows, nMaxCollectionElements);
3351 }
3352
3353 /// \}
3354 // End of the doxygen group for actions
3355 // ----------------------------------------------------------------------------------------
3356
3357 /// \name Immediate Actions
3358 /// Immediate Actions eagerly start the event loop and produce a result.
3359 /// \{
3360
3361 template <typename... ColumnTypes>
3362 [[deprecated("Snapshot is not any more a template. You can safely remove the template parameters.")]]
3364 Snapshot(std::string_view treename, std::string_view filename, const ColumnNames_t &columnList,
3365 const RSnapshotOptions &options = RSnapshotOptions())
3366 {
3367 return Snapshot(treename, filename, columnList, options);
3368 }
3369
3370 ////////////////////////////////////////////////////////////////////////////
3371 /// \brief Save selected columns to disk, in a new TTree or RNTuple `treename` in file `filename`.
3372 /// \param[in] treename The name of the output TTree or RNTuple.
3373 /// \param[in] filename The name of the output TFile.
3374 /// \param[in] columnList The list of names of the columns/branches/fields to be written.
3375 /// \param[in] options RSnapshotOptions struct with extra options to pass to TFile and TTree/RNTuple.
3376 /// \return a `RDataFrame` that wraps the snapshotted dataset.
3377 ///
3378 /// This function returns a `RDataFrame` built with the output TTree or RNTuple as a source.
3379 /// The types of the columns are automatically inferred and do not need to be specified.
3380 ///
3381 /// Support for writing of nested branches/fields is limited (although RDataFrame is able to read them) and dot ('.')
3382 /// characters in input column names will be replaced by underscores ('_') in the branches produced by Snapshot.
3383 /// When writing a variable size array through Snapshot, it is required that the column indicating its size is also
3384 /// written out and it appears before the array in the columnList.
3385 ///
3386 /// By default, in case of TTree, TChain or RNTuple inputs, Snapshot will try to write out all top-level branches.
3387 /// For other types of inputs, all columns returned by GetColumnNames() will be written out. Systematic variations of
3388 /// columns will be included if the corresponding flag is set in RSnapshotOptions. See \ref snapshot-with-variations
3389 /// "Snapshot with Variations" for more details. If friend trees or chains are present, by default all friend
3390 /// top-level branches that have names that do not collide with names of branches in the main TTree/TChain will be
3391 /// written out. Since v6.24, Snapshot will also write out friend branches with the same names of branches in the
3392 /// main TTree/TChain with names of the form
3393 /// `<friendname>_<branchname>` in order to differentiate them from the branches in the main tree/chain.
3394 ///
3395 /// ### Writing to a sub-directory
3396 ///
3397 /// Snapshot supports writing the TTree or RNTuple in a sub-directory inside the TFile. It is sufficient to specify
3398 /// the directory path as part of the TTree or RNTuple name, e.g. `df.Snapshot("subdir/t", "f.root")` writes TTree
3399 /// `t` in the sub-directory `subdir` of file `f.root` (creating file and sub-directory as needed).
3400 ///
3401 /// \attention In multi-thread runs (i.e. when EnableImplicitMT() has been called) threads will loop over clusters of
3402 /// entries in an undefined order, so Snapshot will produce outputs in which (clusters of) entries will be shuffled
3403 /// with respect to the input TTree. Using such "shuffled" TTrees as friends of the original trees would result in
3404 /// wrong associations between entries in the main TTree and entries in the "shuffled" friend. Since v6.22, ROOT will
3405 /// error out if such a "shuffled" TTree is used in a friendship.
3406 ///
3407 /// \note In case no events are written out (e.g. because no event passes all filters), Snapshot will still write the
3408 /// requested output TTree or RNTuple to the file, with all the branches requested to preserve the dataset schema.
3409 ///
3410 /// \note Snapshot will refuse to process columns with names of the form `#columnname`. These are special columns
3411 /// made available by some data sources (e.g. RNTupleDS) that represent the size of column `columnname`, and are
3412 /// not meant to be written out with that name (which is not a valid C++ variable name). Instead, go through an
3413 /// Alias(): `df.Alias("nbar", "#bar").Snapshot(..., {"nbar"})`.
3414 ///
3415 /// ### Example invocations:
3416 ///
3417 /// ~~~{.cpp}
3418 /// // No need to specify column types, they are automatically deduced thanks
3419 /// // to information coming from the data source
3420 /// df.Snapshot("outputTree", "outputFile.root", {"x", "y"});
3421 /// ~~~
3422 ///
3423 /// To book a Snapshot without triggering the event loop, one needs to set the appropriate flag in
3424 /// `RSnapshotOptions`:
3425 /// ~~~{.cpp}
3426 /// RSnapshotOptions opts;
3427 /// opts.fLazy = true;
3428 /// df.Snapshot("outputTree", "outputFile.root", {"x"}, opts);
3429 /// ~~~
3430 ///
3431 /// To snapshot to the RNTuple data format, the `fOutputFormat` option in `RSnapshotOptions` needs to be set
3432 /// accordingly:
3433 /// ~~~{.cpp}
3434 /// RSnapshotOptions opts;
3435 /// opts.fOutputFormat = ROOT::RDF::ESnapshotOutputFormat::kRNTuple;
3436 /// df.Snapshot("outputNTuple", "outputFile.root", {"x"}, opts);
3437 /// ~~~
3438 ///
3439 /// Snapshot systematic variations resulting from a Vary() call (see details \ref snapshot-with-variations "here"):
3440 /// ~~~{.cpp}
3441 /// RSnapshotOptions opts;
3442 /// opts.fIncludeVariations = true;
3443 /// df.Snapshot("outputTree", "outputFile.root", {"x"}, opts);
3444 /// ~~~
3445 RResultPtr<RInterface<RLoopManager>> Snapshot(std::string_view treename, std::string_view filename,
3446 const ColumnNames_t &columnList,
3447 const RSnapshotOptions &options = RSnapshotOptions())
3448 {
3449 // like columnList but with `#var` columns removed
3450 auto colListNoPoundSizes = RDFInternal::FilterArraySizeColNames(columnList, "Snapshot");
3451 // like columnListWithoutSizeColumns but with aliases resolved
3452 auto colListNoAliases = GetValidatedColumnNames(colListNoPoundSizes.size(), colListNoPoundSizes);
3453 RDFInternal::CheckForDuplicateSnapshotColumns(colListNoAliases);
3454 // like validCols but with missing size branches required by array branches added in the right positions
3455 const auto pairOfColumnLists =
3456 RDFInternal::AddSizeBranches(GetDataSource(), std::move(colListNoAliases), std::move(colListNoPoundSizes));
3457 const auto &colListNoAliasesWithSizeBranches = pairOfColumnLists.first;
3458 const auto &colListWithAliasesAndSizeBranches = pairOfColumnLists.second;
3459
3460 const auto fullTreeName = treename;
3461 const auto parsedTreePath = RDFInternal::ParseTreePath(fullTreeName);
3462 treename = parsedTreePath.fTreeName;
3463 const auto &dirname = parsedTreePath.fDirName;
3464
3466
3468
3469 auto retrieveTypeID = [](const std::string &colName, const std::string &colTypeName,
3470 bool isRNTuple = false) -> const std::type_info * {
3471 try {
3472 return &ROOT::Internal::RDF::TypeName2TypeID(colTypeName);
3473 } catch (const std::runtime_error &err) {
3474 if (isRNTuple)
3476
3477 if (std::string(err.what()).find("Cannot extract type_info of type") != std::string::npos) {
3478 // We could not find RTTI for this column, thus we cannot write it out at the moment.
3479 std::string trueTypeName{colTypeName};
3480 if (colTypeName.rfind("CLING_UNKNOWN_TYPE", 0) == 0)
3481 trueTypeName = colTypeName.substr(19);
3482 std::string msg{"No runtime type information is available for column \"" + colName +
3483 "\" with type name \"" + trueTypeName +
3484 "\". Thus, it cannot be written to disk with Snapshot. Make sure to generate and load "
3485 "ROOT dictionaries for the type of this column."};
3486
3487 throw std::runtime_error(msg);
3488 } else {
3489 throw;
3490 }
3491 }
3492 };
3493
3494 RDFInternal::CheckSnapshotOptionsFormatCompatibility(options);
3495
3496 if (options.fOutputFormat == ESnapshotOutputFormat::kRNTuple) {
3497 // The data source of the RNTuple resulting from the Snapshot action does not exist yet here, so we create one
3498 // without a data source for now, and set it once the actual data source can be created (i.e., after
3499 // writing the RNTuple).
3500 auto newRDF = std::make_shared<RInterface<RLoopManager>>(std::make_shared<RLoopManager>(colListNoPoundSizes));
3501
3502 auto snapHelperArgs = std::make_shared<RDFInternal::SnapshotHelperArgs>(RDFInternal::SnapshotHelperArgs{
3503 std::string(filename), std::string(dirname), std::string(treename), colListWithAliasesAndSizeBranches,
3504 options, newRDF->GetLoopManager(), GetLoopManager(), true /* fToNTuple */, /*fIncludeVariations=*/false});
3505
3506 auto &&nColumns = colListNoAliasesWithSizeBranches.size();
3507 const auto validColumnNames = GetValidatedColumnNames(nColumns, colListNoAliasesWithSizeBranches);
3508
3509 const auto nSlots = fLoopManager->GetNSlots();
3510 std::vector<const std::type_info *> colTypeIDs;
3511 colTypeIDs.reserve(nColumns);
3512 for (decltype(nColumns) i{}; i < nColumns; i++) {
3513 const auto &colName = validColumnNames[i];
3514 const auto colTypeName = ROOT::Internal::RDF::ColumnName2ColumnTypeName(
3515 colName, /*tree*/ nullptr, GetDataSource(), fColRegister.GetDefine(colName), options.fVector2RVec);
3516 const std::type_info *colTypeID = retrieveTypeID(colName, colTypeName, /*isRNTuple*/ true);
3517 colTypeIDs.push_back(colTypeID);
3518 }
3519 // Crucial e.g. if the column names do not correspond to already-available column readers created by the data
3520 // source
3521 CheckAndFillDSColumns(validColumnNames, colTypeIDs);
3522
3523 auto action =
3524 RDFInternal::BuildAction(validColumnNames, snapHelperArgs, nSlots, fProxiedPtr, fColRegister, colTypeIDs);
3525 resPtr = MakeResultPtr(newRDF, *GetLoopManager(), std::move(action));
3526 } else {
3527 if (RDFInternal::GetDataSourceLabel(*this) == "RNTupleDS" &&
3528 options.fOutputFormat == ESnapshotOutputFormat::kDefault) {
3529 Warning("Snapshot",
3530 "The default Snapshot output data format is TTree, but the input data format is RNTuple. If you "
3531 "want to Snapshot to RNTuple or suppress this warning, set the appropriate fOutputFormat option in "
3532 "RSnapshotOptions. Note that this current default behaviour might change in the future.");
3533 }
3534
3535 // We create an RLoopManager without a data source. This needs to be initialised when the output TTree dataset
3536 // has actually been created and written to TFile, i.e. at the end of the Snapshot execution.
3537 auto newRDF = std::make_shared<RInterface<RLoopManager>>(
3538 std::make_shared<RLoopManager>(colListNoAliasesWithSizeBranches));
3539
3540 auto snapHelperArgs = std::make_shared<RDFInternal::SnapshotHelperArgs>(RDFInternal::SnapshotHelperArgs{
3541 std::string(filename), std::string(dirname), std::string(treename), colListWithAliasesAndSizeBranches,
3542 options, newRDF->GetLoopManager(), GetLoopManager(), false /* fToRNTuple */, options.fIncludeVariations});
3543
3544 auto &&nColumns = colListNoAliasesWithSizeBranches.size();
3545 const auto validColumnNames = GetValidatedColumnNames(nColumns, colListNoAliasesWithSizeBranches);
3546
3547 const auto nSlots = fLoopManager->GetNSlots();
3548 std::vector<const std::type_info *> colTypeIDs;
3549 colTypeIDs.reserve(nColumns);
3550 for (decltype(nColumns) i{}; i < nColumns; i++) {
3551 const auto &colName = validColumnNames[i];
3552 const auto colTypeName = ROOT::Internal::RDF::ColumnName2ColumnTypeName(
3553 colName, /*tree*/ nullptr, GetDataSource(), fColRegister.GetDefine(colName), options.fVector2RVec);
3554 const std::type_info *colTypeID = retrieveTypeID(colName, colTypeName);
3555 colTypeIDs.push_back(colTypeID);
3556 }
3557 // Crucial e.g. if the column names do not correspond to already-available column readers created by the data
3558 // source
3559 CheckAndFillDSColumns(validColumnNames, colTypeIDs);
3560
3561 auto action =
3562 RDFInternal::BuildAction(validColumnNames, snapHelperArgs, nSlots, fProxiedPtr, fColRegister, colTypeIDs);
3563 resPtr = MakeResultPtr(newRDF, *GetLoopManager(), std::move(action));
3564 }
3565
3566 if (!options.fLazy)
3567 *resPtr;
3568 return resPtr;
3569 }
3570
3571 // clang-format off
3572 ////////////////////////////////////////////////////////////////////////////
3573 /// \brief Save selected columns to disk, in a new TTree or RNTuple `treename` in file `filename`.
3574 /// \param[in] treename The name of the output TTree or RNTuple.
3575 /// \param[in] filename The name of the output TFile.
3576 /// \param[in] columnNameRegexp The regular expression to match the column names to be selected. The presence of a '^' and a '$' at the end of the string is implicitly assumed if they are not specified. The dialect supported is PCRE via the TPRegexp class. An empty string signals the selection of all columns.
3577 /// \param[in] options RSnapshotOptions struct with extra options to pass to TFile and TTree/RNTuple
3578 /// \return a `RDataFrame` that wraps the snapshotted dataset.
3579 ///
3580 /// This function returns a `RDataFrame` built with the output TTree or RNTuple as a source.
3581 /// The types of the columns are automatically inferred and do not need to be specified.
3582 ///
3583 /// See Snapshot(std::string_view, std::string_view, const ColumnNames_t&, const RSnapshotOptions &) for a more complete description and example usages.
3584 RResultPtr<RInterface<RLoopManager>> Snapshot(std::string_view treename, std::string_view filename,
3585 std::string_view columnNameRegexp = "",
3586 const RSnapshotOptions &options = RSnapshotOptions())
3587 {
3588 const auto definedColumns = fColRegister.GenerateColumnNames();
3589
3591 // Ignore R_rdf_sizeof_* columns coming from datasources: we don't want to Snapshot those
3592 ColumnNames_t dsColumnsWithoutSizeColumns;
3593 std::copy_if(dsColumns.begin(), dsColumns.end(), std::back_inserter(dsColumnsWithoutSizeColumns),
3594 [](const std::string &name) { return name.size() < 13 || name.substr(0, 13) != "R_rdf_sizeof_"; });
3595 ColumnNames_t columnNames;
3596 columnNames.reserve(definedColumns.size() + dsColumnsWithoutSizeColumns.size());
3597 columnNames.insert(columnNames.end(), definedColumns.begin(), definedColumns.end());
3598 columnNames.insert(columnNames.end(), dsColumnsWithoutSizeColumns.begin(), dsColumnsWithoutSizeColumns.end());
3599
3600 // The only way we can get duplicate entries is if a column coming from a tree or data-source is Redefine'd.
3601 // RemoveDuplicates should preserve ordering of the columns: it might be meaningful.
3602 RDFInternal::RemoveDuplicates(columnNames);
3603
3604 std::vector<std::string> selectedColumns;
3605 try {
3606 selectedColumns = RDFInternal::ConvertRegexToColumns(columnNames, columnNameRegexp, "Snapshot");
3607 }
3608 catch (const std::runtime_error &e){
3609 // No columns were found, try again but consider all input data source columns
3610 if (auto ds = GetDataSource())
3611 selectedColumns = RDFInternal::ConvertRegexToColumns(ds->GetColumnNames(), columnNameRegexp, "Snapshot");
3612 else
3613 throw e;
3614 }
3615
3616 if (RDFInternal::GetDataSourceLabel(*this) == "RNTupleDS") {
3617 RDFInternal::RemoveRNTupleSubfields(selectedColumns);
3618 }
3619
3620 return Snapshot(treename, filename, selectedColumns, options);
3621 }
3622 // clang-format on
3623
3624 // clang-format off
3625 ////////////////////////////////////////////////////////////////////////////
3626 /// \brief Save selected columns to disk, in a new TTree or RNTuple `treename` in file `filename`.
3627 /// \param[in] treename The name of the output TTree or RNTuple.
3628 /// \param[in] filename The name of the output TFile.
3629 /// \param[in] columnList The list of names of the columns/branches to be written.
3630 /// \param[in] options RSnapshotOptions struct with extra options to pass to TFile and TTree/RNTuple.
3631 /// \return a `RDataFrame` that wraps the snapshotted dataset.
3632 ///
3633 /// This function returns a `RDataFrame` built with the output TTree or RNTuple as a source.
3634 /// The types of the columns are automatically inferred and do not need to be specified.
3635 ///
3636 /// See Snapshot(std::string_view, std::string_view, const ColumnNames_t&, const RSnapshotOptions &) for a more complete description and example usages.
3637 RResultPtr<RInterface<RLoopManager>> Snapshot(std::string_view treename, std::string_view filename,
3638 std::initializer_list<std::string> columnList,
3639 const RSnapshotOptions &options = RSnapshotOptions())
3640 {
3641 ColumnNames_t selectedColumns(columnList);
3642 return Snapshot(treename, filename, selectedColumns, options);
3643 }
3644 // clang-format on
3645
3646 ////////////////////////////////////////////////////////////////////////////
3647 /// \brief Save selected columns in memory.
3648 /// \tparam ColumnTypes variadic list of branch/column types.
3649 /// \param[in] columnList columns to be cached in memory.
3650 /// \return a `RDataFrame` that wraps the cached dataset.
3651 ///
3652 /// This action returns a new `RDataFrame` object, completely detached from
3653 /// the originating `RDataFrame`. The new dataframe only contains the cached
3654 /// columns and stores their content in memory for fast, zero-copy subsequent access.
3655 ///
3656 /// Use `Cache` if you know you will only need a subset of the (`Filter`ed) data that
3657 /// fits in memory and that will be accessed many times.
3658 ///
3659 /// \note Cache will refuse to process columns with names of the form `#columnname`. These are special columns
3660 /// made available by some data sources (e.g. RNTupleDS) that represent the size of column `columnname`, and are
3661 /// not meant to be written out with that name (which is not a valid C++ variable name). Instead, go through an
3662 /// Alias(): `df.Alias("nbar", "#bar").Cache<std::size_t>(..., {"nbar"})`.
3663 ///
3664 /// ### Example usage:
3665 ///
3666 /// **Types and columns specified:**
3667 /// ~~~{.cpp}
3668 /// auto cache_some_cols_df = df.Cache<double, MyClass, int>({"col0", "col1", "col2"});
3669 /// ~~~
3670 ///
3671 /// **Types inferred and columns specified (this invocation relies on jitting):**
3672 /// ~~~{.cpp}
3673 /// auto cache_some_cols_df = df.Cache({"col0", "col1", "col2"});
3674 /// ~~~
3675 ///
3676 /// **Types inferred and columns selected with a regexp (this invocation relies on jitting):**
3677 /// ~~~{.cpp}
3678 /// auto cache_all_cols_df = df.Cache(myRegexp);
3679 /// ~~~
3680 template <typename... ColumnTypes>
3682 {
3683 auto staticSeq = std::make_index_sequence<sizeof...(ColumnTypes)>();
3684 return CacheImpl<ColumnTypes...>(columnList, staticSeq);
3685 }
3686
3687 ////////////////////////////////////////////////////////////////////////////
3688 /// \brief Save selected columns in memory.
3689 /// \param[in] columnList columns to be cached in memory
3690 /// \return a `RDataFrame` that wraps the cached dataset.
3691 ///
3692 /// See the previous overloads for more information.
3694 {
3695 // Early return: if the list of columns is empty, just return an empty RDF
3696 // If we proceed, the jitted call will not compile!
3697 if (columnList.empty()) {
3698 auto nEntries = *this->Count();
3699 RInterface<RLoopManager> emptyRDF(std::make_shared<RLoopManager>(nEntries));
3700 return emptyRDF;
3701 }
3702
3703 std::stringstream cacheCall;
3704 auto upcastNode = RDFInternal::UpcastNode(fProxiedPtr);
3705 RInterface<TTraits::TakeFirstParameter_t<decltype(upcastNode)>> upcastInterface(fProxiedPtr, *fLoopManager,
3706 fColRegister);
3707 // build a string equivalent to
3708 // "(RInterface<nodetype*>*)(this)->Cache<Ts...>(*(ColumnNames_t*)(&columnList))"
3709 RInterface<RLoopManager> resRDF(std::make_shared<ROOT::Detail::RDF::RLoopManager>(0));
3710 cacheCall << "*reinterpret_cast<ROOT::RDF::RInterface<ROOT::Detail::RDF::RLoopManager>*>("
3712 << ") = reinterpret_cast<ROOT::RDF::RInterface<ROOT::Detail::RDF::RNodeBase>*>("
3713 << RDFInternal::PrettyPrintAddr(&upcastInterface) << ")->Cache<";
3714
3715 const auto columnListWithoutSizeColumns = RDFInternal::FilterArraySizeColNames(columnList, "Cache");
3716
3717 const auto validColumnNames =
3718 GetValidatedColumnNames(columnListWithoutSizeColumns.size(), columnListWithoutSizeColumns);
3719 const auto colTypes =
3720 GetValidatedArgTypes(validColumnNames, fColRegister, nullptr, GetDataSource(), "Cache", /*vector2RVec=*/false);
3721 for (const auto &colType : colTypes)
3722 cacheCall << colType << ", ";
3723 if (!columnListWithoutSizeColumns.empty())
3724 cacheCall.seekp(-2, cacheCall.cur); // remove the last ",
3725 cacheCall << ">(*reinterpret_cast<std::vector<std::string>*>(" // vector<string> should be ColumnNames_t
3726 << RDFInternal::PrettyPrintAddr(&columnListWithoutSizeColumns) << "));";
3727
3728 // book the code to jit with the RLoopManager and trigger the event loop
3729 fLoopManager->ToJitExec(cacheCall.str());
3730 fLoopManager->Jit();
3731
3732 return resRDF;
3733 }
3734
3735 ////////////////////////////////////////////////////////////////////////////
3736 /// \brief Save selected columns in memory.
3737 /// \param[in] columnNameRegexp The regular expression to match the column names to be selected. The presence of a '^' and a '$' at the end of the string is implicitly assumed if they are not specified. The dialect supported is PCRE via the TPRegexp class. An empty string signals the selection of all columns.
3738 /// \return a `RDataFrame` that wraps the cached dataset.
3739 ///
3740 /// The existing columns are matched against the regular expression. If the string provided
3741 /// is empty, all columns are selected. See the previous overloads for more information.
3742 RInterface<RLoopManager> Cache(std::string_view columnNameRegexp = "")
3743 {
3744 const auto definedColumns = fColRegister.GenerateColumnNames();
3745 const auto dsColumns = GetDataSource() ? GetDataSource()->GetColumnNames() : ColumnNames_t{};
3746 // Ignore R_rdf_sizeof_* columns coming from datasources: we don't want to Snapshot those
3747 ColumnNames_t dsColumnsWithoutSizeColumns;
3748 std::copy_if(dsColumns.begin(), dsColumns.end(), std::back_inserter(dsColumnsWithoutSizeColumns),
3749 [](const std::string &name) { return name.size() < 13 || name.substr(0, 13) != "R_rdf_sizeof_"; });
3750 ColumnNames_t columnNames;
3751 columnNames.reserve(definedColumns.size() + dsColumns.size());
3752 columnNames.insert(columnNames.end(), definedColumns.begin(), definedColumns.end());
3753 columnNames.insert(columnNames.end(), dsColumns.begin(), dsColumns.end());
3754 const auto selectedColumns = RDFInternal::ConvertRegexToColumns(columnNames, columnNameRegexp, "Cache");
3755 return Cache(selectedColumns);
3756 }
3757
3758 ////////////////////////////////////////////////////////////////////////////
3759 /// \brief Save selected columns in memory.
3760 /// \param[in] columnList columns to be cached in memory.
3761 /// \return a `RDataFrame` that wraps the cached dataset.
3762 ///
3763 /// See the previous overloads for more information.
3764 RInterface<RLoopManager> Cache(std::initializer_list<std::string> columnList)
3765 {
3766 ColumnNames_t selectedColumns(columnList);
3767 return Cache(selectedColumns);
3768 }
3769
3770
3771 // clang-format off
3772 ////////////////////////////////////////////////////////////////////////////
3773 /// \brief Execute a user-defined function on each entry (*instant action*).
3774 /// \param[in] f Function, lambda expression, functor class or any other callable object performing user defined calculations.
3775 /// \param[in] columns Names of the columns/branches in input to the user function.
3776 ///
3777 /// The callable `f` is invoked once per entry. This is an *instant action*:
3778 /// upon invocation, an event loop as well as execution of all scheduled actions
3779 /// is triggered.
3780 /// Users are responsible for the thread-safety of this callable when executing
3781 /// with implicit multi-threading enabled (i.e. ROOT::EnableImplicitMT).
3782 ///
3783 /// ### Example usage:
3784 /// ~~~{.cpp}
3785 /// myDf.Foreach([](int i){ std::cout << i << std::endl;}, {"myIntColumn"});
3786 /// ~~~
3787 // clang-format on
3788 template <typename F>
3789 void Foreach(F f, const ColumnNames_t &columns = {})
3790 {
3791 using arg_types = typename TTraits::CallableTraits<decltype(f)>::arg_types_nodecay;
3792 using ret_type = typename TTraits::CallableTraits<decltype(f)>::ret_type;
3793 ForeachSlot(RDFInternal::AddSlotParameter<ret_type>(f, arg_types()), columns);
3794 }
3795
3796 // clang-format off
3797 ////////////////////////////////////////////////////////////////////////////
3798 /// \brief Execute a user-defined function requiring a processing slot index on each entry (*instant action*).
3799 /// \param[in] f Function, lambda expression, functor class or any other callable object performing user defined calculations.
3800 /// \param[in] columns Names of the columns/branches in input to the user function.
3801 ///
3802 /// Same as `Foreach`, but the user-defined function takes an extra
3803 /// `unsigned int` as its first parameter, the *processing slot index*.
3804 /// This *slot index* will be assigned a different value, `0` to `poolSize - 1`,
3805 /// for each thread of execution.
3806 /// This is meant as a helper in writing thread-safe `Foreach`
3807 /// actions when using `RDataFrame` after `ROOT::EnableImplicitMT()`.
3808 /// The user-defined processing callable is able to follow different
3809 /// *streams of processing* indexed by the first parameter.
3810 /// `ForeachSlot` works just as well with single-thread execution: in that
3811 /// case `slot` will always be `0`.
3812 ///
3813 /// ### Example usage:
3814 /// ~~~{.cpp}
3815 /// myDf.ForeachSlot([](unsigned int s, int i){ std::cout << "Slot " << s << ": "<< i << std::endl;}, {"myIntColumn"});
3816 /// ~~~
3817 // clang-format on
3818 template <typename F>
3819 void ForeachSlot(F f, const ColumnNames_t &columns = {})
3820 {
3822 constexpr auto nColumns = ColTypes_t::list_size;
3823
3824 const auto validColumnNames = GetValidatedColumnNames(nColumns, columns);
3825 CheckAndFillDSColumns(validColumnNames, ColTypes_t());
3826
3827 using Helper_t = RDFInternal::ForeachSlotHelper<F>;
3829
3830 auto action = std::make_unique<Action_t>(Helper_t(std::move(f)), validColumnNames, fProxiedPtr, fColRegister);
3831
3832 fLoopManager->Run();
3833 }
3834
3835 /// \}
3836 // End of doxygen group for immediate actions
3837 // ----------------------------------------------------------------------------------------
3838
3839 /// \brief Returns the names of the filters created.
3840 /// \return the container of filters names.
3841 ///
3842 /// If called on a root node, all the filters in the computation graph will
3843 /// be printed. For any other node, only the filters upstream of that node.
3844 /// Filters without a name are printed as "Unnamed Filter"
3845 /// This is not an action nor a transformation, just a query to the RDataFrame object.
3846 ///
3847 /// ### Example usage:
3848 /// ~~~{.cpp}
3849 /// auto filtNames = d.GetFilterNames();
3850 /// for (auto &&filtName : filtNames) std::cout << filtName << std::endl;
3851 /// ~~~
3852 ///
3853 std::vector<std::string> GetFilterNames() { return RDFInternal::GetFilterNames(fProxiedPtr); }
3854
3855 /// \name User-defined Actions (lazy)
3856 /// Pass user-defined functions to be applied to the data and create results.
3857 /// These actions are lazy, i.e., they only run once a result is actually requested.
3858 /// \{
3859
3860 // clang-format off
3861 ////////////////////////////////////////////////////////////////////////////
3862 /// \brief Execute a user-defined accumulation operation on the processed column values in each processing slot.
3863 /// \tparam F The type of the aggregator callable. Automatically deduced.
3864 /// \tparam U The type of the aggregator variable. Must be default-constructible, copy-constructible and copy-assignable. Automatically deduced.
3865 /// \tparam T The type of the column to apply the reduction to. Automatically deduced.
3866 /// \param[in] aggregator A callable with signature `U(U,T)` or `void(U&,T)`, where T is the type of the column, U is the type of the aggregator variable
3867 /// \param[in] merger A callable with signature `U(U,U)` or `void(std::vector<U>&)` used to merge the results of the accumulations of each thread
3868 /// \param[in] columnName The column to be aggregated. If omitted, the first default column is used instead.
3869 /// \param[in] aggIdentity The aggregator variable of each thread is initialized to this value (or is default-constructed if the parameter is omitted)
3870 /// \return the result of the aggregation wrapped in a RResultPtr.
3871 ///
3872 /// An aggregator callable takes two values, an aggregator variable and a column value. The aggregator variable is
3873 /// initialized to aggIdentity or default-constructed if aggIdentity is omitted.
3874 /// This action calls the aggregator callable for each processed entry, passing in the aggregator variable and
3875 /// the value of the column columnName.
3876 /// If the signature is `U(U,T)` the aggregator variable is then copy-assigned the result of the execution of the callable.
3877 /// Otherwise the signature of aggregator must be `void(U&,T)`.
3878 ///
3879 /// The merger callable is used to merge the partial accumulation results of each processing thread. It is only called in multi-thread executions.
3880 /// If its signature is `U(U,U)` the aggregator variables of each thread are merged two by two.
3881 /// If its signature is `void(std::vector<U>& a)` it is assumed that it merges all aggregators in a[0].
3882 ///
3883 /// This action is *lazy*: upon invocation of this method the calculation is booked but not executed. Also see RResultPtr.
3884 ///
3885 /// Example usage:
3886 /// ~~~{.cpp}
3887 /// auto aggregator = [](double acc, double x) { return acc * x; };
3888 /// ROOT::EnableImplicitMT();
3889 /// // If multithread is enabled, the aggregator function will be called by more threads
3890 /// // and will produce a vector of partial accumulators.
3891 /// // The merger function performs the final aggregation of these partial results.
3892 /// auto merger = [](std::vector<double> &accumulators) {
3893 /// for (auto i : ROOT::TSeqU(1u, accumulators.size())) {
3894 /// accumulators[0] *= accumulators[i];
3895 /// }
3896 /// };
3897 ///
3898 /// // The accumulator is initialized at this value by every thread.
3899 /// double initValue = 1.;
3900 ///
3901 /// // Multiplies all elements of the column "x"
3902 /// auto result = d.Aggregate(aggregator, merger, "x", initValue);
3903 /// ~~~
3904 // clang-format on
3905 template <typename AccFun, typename MergeFun, typename R = typename TTraits::CallableTraits<AccFun>::ret_type,
3906 typename ArgTypes = typename TTraits::CallableTraits<AccFun>::arg_types,
3907 typename ArgTypesNoDecay = typename TTraits::CallableTraits<AccFun>::arg_types_nodecay,
3908 typename U = TTraits::TakeFirstParameter_t<ArgTypes>,
3909 typename T = TTraits::TakeFirstParameter_t<TTraits::RemoveFirstParameter_t<ArgTypes>>>
3910 RResultPtr<U> Aggregate(AccFun aggregator, MergeFun merger, std::string_view columnName, const U &aggIdentity)
3911 {
3912 RDFInternal::CheckAggregate<R, MergeFun>(ArgTypesNoDecay());
3913 const auto columns = columnName.empty() ? ColumnNames_t() : ColumnNames_t({std::string(columnName)});
3914
3915 const auto validColumnNames = GetValidatedColumnNames(1, columns);
3916 CheckAndFillDSColumns(validColumnNames, TTraits::TypeList<T>());
3917
3918 auto accObjPtr = std::make_shared<U>(aggIdentity);
3919 using Helper_t = RDFInternal::AggregateHelper<AccFun, MergeFun, R, T, U>;
3921 auto action = std::make_unique<Action_t>(
3922 Helper_t(std::move(aggregator), std::move(merger), accObjPtr, fLoopManager->GetNSlots()), validColumnNames,
3924 return MakeResultPtr(accObjPtr, *fLoopManager, std::move(action));
3925 }
3926
3927 // clang-format off
3928 ////////////////////////////////////////////////////////////////////////////
3929 /// \brief Execute a user-defined accumulation operation on the processed column values in each processing slot.
3930 /// \tparam F The type of the aggregator callable. Automatically deduced.
3931 /// \tparam U The type of the aggregator variable. Must be default-constructible, copy-constructible and copy-assignable. Automatically deduced.
3932 /// \tparam T The type of the column to apply the reduction to. Automatically deduced.
3933 /// \param[in] aggregator A callable with signature `U(U,T)` or `void(U,T)`, where T is the type of the column, U is the type of the aggregator variable
3934 /// \param[in] merger A callable with signature `U(U,U)` or `void(std::vector<U>&)` used to merge the results of the accumulations of each thread
3935 /// \param[in] columnName The column to be aggregated. If omitted, the first default column is used instead.
3936 /// \return the result of the aggregation wrapped in a RResultPtr.
3937 ///
3938 /// See previous Aggregate overload for more information.
3939 // clang-format on
3940 template <typename AccFun, typename MergeFun, typename R = typename TTraits::CallableTraits<AccFun>::ret_type,
3941 typename ArgTypes = typename TTraits::CallableTraits<AccFun>::arg_types,
3942 typename U = TTraits::TakeFirstParameter_t<ArgTypes>,
3943 typename T = TTraits::TakeFirstParameter_t<TTraits::RemoveFirstParameter_t<ArgTypes>>>
3944 RResultPtr<U> Aggregate(AccFun aggregator, MergeFun merger, std::string_view columnName = "")
3945 {
3946 static_assert(
3947 std::is_default_constructible<U>::value,
3948 "aggregated object cannot be default-constructed. Please provide an initialisation value (aggIdentity)");
3949 return Aggregate(std::move(aggregator), std::move(merger), columnName, U());
3950 }
3951
3952 // clang-format off
3953 ////////////////////////////////////////////////////////////////////////////
3954 /// \brief Book execution of a custom action using a user-defined helper object.
3955 /// \tparam FirstColumn The type of the first column used by this action. Inferred together with OtherColumns if not present.
3956 /// \tparam OtherColumns A list of the types of the other columns used by this action
3957 /// \tparam Helper The type of the user-defined helper. See below for the required interface it should expose.
3958 /// \param[in] helper The Action Helper to be scheduled.
3959 /// \param[in] columns The names of the columns on which the helper acts.
3960 /// \return the result of the helper wrapped in a RResultPtr.
3961 ///
3962 /// This method books a custom action for execution. The behavior of the action is completely dependent on the
3963 /// Helper object provided by the caller. The required interface for the helper is described below (more
3964 /// methods that the ones required can be present, e.g. a constructor that takes the number of worker threads is usually useful):
3965 ///
3966 /// ### Mandatory interface
3967 ///
3968 /// * `Helper` must publicly inherit from `ROOT::Detail::RDF::RActionImpl<Helper>`
3969 /// * `Helper::Result_t`: public alias for the type of the result of this action helper. `Result_t` must be default-constructible.
3970 /// * `Helper(Helper &&)`: a move-constructor is required. Copy-constructors are discouraged.
3971 /// * `std::shared_ptr<Result_t> GetResultPtr() const`: return a shared_ptr to the result of this action (of type
3972 /// Result_t). The RResultPtr returned by Book will point to this object. Note that this method can be called
3973 /// _before_ Initialize(), because the RResultPtr is constructed before the event loop is started.
3974 /// * `void Initialize()`: this method is called once before starting the event-loop. Useful for setup operations.
3975 /// It must reset the state of the helper to the expected state at the beginning of the event loop: the same helper,
3976 /// or copies of it, might be used for multiple event loops (e.g. in the presence of systematic variations).
3977 /// * `void InitTask(TTreeReader *, unsigned int slot)`: each working thread shall call this method during the event
3978 /// loop, before processing a batch of entries. The pointer passed as argument, if not null, will point to the TTreeReader
3979 /// that RDataFrame has set up to read the task's batch of entries. It is passed to the helper to allow certain advanced optimizations
3980 /// it should not usually serve any purpose for the Helper. This method is often no-op for simple helpers.
3981 /// * `void Exec(unsigned int slot, ColumnTypes...columnValues)`: each working thread shall call this method
3982 /// during the event-loop, possibly concurrently. No two threads will ever call Exec with the same 'slot' value:
3983 /// this parameter is there to facilitate writing thread-safe helpers. The other arguments will be the values of
3984 /// the requested columns for the particular entry being processed.
3985 /// * `void Finalize()`: this method is called at the end of the event loop. Commonly used to finalize the contents of the result.
3986 /// * `std::string GetActionName()`: it returns a string identifier for this type of action that RDataFrame will use in
3987 /// diagnostics, SaveGraph(), etc.
3988 ///
3989 /// ### Optional methods
3990 ///
3991 /// If these methods are implemented they enable extra functionality as per the description below.
3992 ///
3993 /// * `Result_t &PartialUpdate(unsigned int slot)`: if present, it must return the value of the partial result of this action for the given 'slot'.
3994 /// Different threads might call this method concurrently, but will do so with different 'slot' numbers.
3995 /// RDataFrame leverages this method to implement RResultPtr::OnPartialResult().
3996 /// * `ROOT::RDF::SampleCallback_t GetSampleCallback()`: if present, it must return a callable with the
3997 /// appropriate signature (see ROOT::RDF::SampleCallback_t) that will be invoked at the beginning of the processing
3998 /// of every sample, as in DefinePerSample().
3999 /// * `Helper MakeNew(void *newResult, std::string_view variation = "nominal")`: if implemented, it enables varying
4000 /// the action's result with VariationsFor(). It takes a type-erased new result that can be safely cast to a
4001 /// `std::shared_ptr<Result_t> *` (a pointer to shared pointer) and should be used as the action's output result.
4002 /// The function optionally takes the name of the current variation which could be useful in customizing its behaviour.
4003 ///
4004 /// In case Book is called without specifying column types as template arguments, corresponding typed code will be just-in-time compiled
4005 /// by RDataFrame. In that case the Helper class needs to be known to the ROOT interpreter.
4006 ///
4007 /// This action is *lazy*: upon invocation of this method the calculation is booked but not executed. Also see RResultPtr.
4008 ///
4009 /// ### Examples
4010 /// See [this tutorial](https://root.cern/doc/master/df018__customActions_8C.html) for an example implementation of an action helper.
4011 ///
4012 /// It is also possible to inspect the code used by built-in RDataFrame actions at ActionHelpers.hxx.
4013 ///
4014 // clang-format on
4015 template <typename FirstColumn = RDFDetail::RInferredType, typename... OtherColumns, typename Helper>
4017 {
4018 using HelperT = std::decay_t<Helper>;
4019 // TODO add more static sanity checks on Helper
4021 static_assert(std::is_base_of<AH, HelperT>::value && std::is_convertible<HelperT *, AH *>::value,
4022 "Action helper of type T must publicly inherit from ROOT::Detail::RDF::RActionImpl<T>");
4023
4024 auto hPtr = std::make_shared<HelperT>(std::forward<Helper>(helper));
4025 auto resPtr = hPtr->GetResultPtr();
4026
4027 if (std::is_same<FirstColumn, RDFDetail::RInferredType>::value && columns.empty()) {
4028 return CallCreateActionWithoutColsIfPossible<HelperT>(resPtr, hPtr, TTraits::TypeList<FirstColumn>{});
4029 } else {
4030 return CreateAction<RDFInternal::ActionTags::Book, FirstColumn, OtherColumns...>(columns, resPtr, hPtr,
4031 fProxiedPtr, columns.size());
4032 }
4033 }
4034
4035
4036 // clang-format off
4037 ////////////////////////////////////////////////////////////////////////////
4038 /// \brief Execute a user-defined reduce operation on the values of a column.
4039 /// \tparam F The type of the reduce callable. Automatically deduced.
4040 /// \tparam T The type of the column to apply the reduction to. Automatically deduced.
4041 /// \param[in] f A callable with signature `T(T,T)`
4042 /// \param[in] columnName The column to be reduced. If omitted, the first default column is used instead.
4043 /// \return the reduced quantity wrapped in a ROOT::RDF:RResultPtr.
4044 ///
4045 /// A reduction takes two values of a column and merges them into one (e.g.
4046 /// by summing them, taking the maximum, etc). This action performs the
4047 /// specified reduction operation on all processed column values, returning
4048 /// a single value of the same type. The callable f must satisfy the general
4049 /// requirements of a *processing function* besides having signature `T(T,T)`
4050 /// where `T` is the type of column columnName.
4051 ///
4052 /// The returned reduced value of each thread (e.g. the initial value of a sum) is initialized to a
4053 /// default-constructed T object. This is commonly expected to be the neutral/identity element for the specific
4054 /// reduction operation `f` (e.g. 0 for a sum, 1 for a product). If a default-constructed T does not satisfy this
4055 /// requirement, users should explicitly specify an initialization value for T by calling the appropriate `Reduce`
4056 /// overload.
4057 ///
4058 /// ### Example usage:
4059 /// ~~~{.cpp}
4060 /// auto sumOfIntCol = d.Reduce([](int x, int y) { return x + y; }, "intCol");
4061 /// ~~~
4062 ///
4063 /// This action is *lazy*: upon invocation of this method the calculation is
4064 /// booked but not executed. Also see RResultPtr.
4065 // clang-format on
4066 template <typename F, typename T = typename TTraits::CallableTraits<F>::ret_type>
4067 RResultPtr<T> Reduce(F f, std::string_view columnName = "")
4068 {
4069 static_assert(
4070 std::is_default_constructible<T>::value,
4071 "reduce object cannot be default-constructed. Please provide an initialisation value (redIdentity)");
4072 return Reduce(std::move(f), columnName, T());
4073 }
4074
4075 ////////////////////////////////////////////////////////////////////////////
4076 /// \brief Execute a user-defined reduce operation on the values of a column.
4077 /// \tparam F The type of the reduce callable. Automatically deduced.
4078 /// \tparam T The type of the column to apply the reduction to. Automatically deduced.
4079 /// \param[in] f A callable with signature `T(T,T)`
4080 /// \param[in] columnName The column to be reduced. If omitted, the first default column is used instead.
4081 /// \param[in] redIdentity The reduced object of each thread is initialized to this value.
4082 /// \return the reduced quantity wrapped in a RResultPtr.
4083 ///
4084 /// ### Example usage:
4085 /// ~~~{.cpp}
4086 /// auto sumOfIntColWithOffset = d.Reduce([](int x, int y) { return x + y; }, "intCol", 42);
4087 /// ~~~
4088 /// See the description of the first Reduce overload for more information.
4089 template <typename F, typename T = typename TTraits::CallableTraits<F>::ret_type>
4090 RResultPtr<T> Reduce(F f, std::string_view columnName, const T &redIdentity)
4091 {
4092 return Aggregate(f, f, columnName, redIdentity);
4093 }
4094
4095 /// \}
4096 // End of the doxygen group for user-defined actions
4097
4098private:
4099 template <typename F, typename DefineType, typename RetType = typename TTraits::CallableTraits<F>::ret_type>
4100 std::enable_if_t<std::is_default_constructible<RetType>::value, RInterface<Proxied>>
4101 DefineImpl(std::string_view name, F &&expression, const ColumnNames_t &columns, const std::string &where)
4102 {
4103 if (where.compare(0, 8, "Redefine") != 0) { // not a Redefine
4104 RDFInternal::CheckValidCppVarName(name, where);
4105 RDFInternal::CheckForRedefinition(where, name, fColRegister,
4107 } else {
4108 RDFInternal::CheckForDefinition(where, name, fColRegister,
4110 RDFInternal::CheckForNoVariations(where, name, fColRegister);
4111 }
4112
4113 using ArgTypes_t = typename TTraits::CallableTraits<F>::arg_types;
4114 using ColTypesTmp_t = typename RDFInternal::RemoveFirstParameterIf<
4115 std::is_same<DefineType, RDFDetail::ExtraArgsForDefine::Slot>::value, ArgTypes_t>::type;
4116 using ColTypes_t = typename RDFInternal::RemoveFirstTwoParametersIf<
4117 std::is_same<DefineType, RDFDetail::ExtraArgsForDefine::SlotAndEntry>::value, ColTypesTmp_t>::type;
4118
4119 constexpr auto nColumns = ColTypes_t::list_size;
4120
4121 const auto validColumnNames = GetValidatedColumnNames(nColumns, columns);
4122 CheckAndFillDSColumns(validColumnNames, ColTypes_t());
4123
4124 // Declare return type to the interpreter, for future use by jitted actions
4125 auto retTypeName = RDFInternal::TypeID2TypeName(typeid(RetType));
4126 if (retTypeName.empty()) {
4127 // The type is not known to the interpreter.
4128 // We must not error out here, but if/when this column is used in jitted code
4129 const auto demangledType = RDFInternal::DemangleTypeIdName(typeid(RetType));
4130 retTypeName = "CLING_UNKNOWN_TYPE_" + demangledType;
4131 }
4132
4133 using NewCol_t = RDFDetail::RDefine<F, DefineType>;
4134 auto newColumn = std::make_shared<NewCol_t>(name, retTypeName, std::forward<F>(expression), validColumnNames,
4136
4138 newCols.AddDefine(std::move(newColumn));
4139
4140 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newCols));
4141
4142 return newInterface;
4143 }
4144
4145 // This overload is chosen when the callable passed to Define or DefineSlot returns void.
4146 // It simply fires a compile-time error. This is preferable to a static_assert in the main `Define` overload because
4147 // this way compilation of `Define` has no way to continue after throwing the error.
4148 template <typename F, typename DefineType, typename RetType = typename TTraits::CallableTraits<F>::ret_type,
4149 bool IsFStringConv = std::is_convertible<F, std::string>::value,
4150 bool IsRetTypeDefConstr = std::is_default_constructible<RetType>::value>
4151 std::enable_if_t<!IsFStringConv && !IsRetTypeDefConstr, RInterface<Proxied>>
4152 DefineImpl(std::string_view, F, const ColumnNames_t &, const std::string &)
4153 {
4154 static_assert(std::is_default_constructible<typename TTraits::CallableTraits<F>::ret_type>::value,
4155 "Error in `Define`: type returned by expression is not default-constructible");
4156 return *this; // never reached
4157 }
4158
4159 ////////////////////////////////////////////////////////////////////////////
4160 /// \brief Implementation of DefinePerSample and RedefinePerSample (non-jitted).
4161 template <typename F, typename RetType_t = typename TTraits::CallableTraits<F>::ret_type>
4162 RInterface<Proxied> DefinePerSampleImpl(std::string_view name, F expression, bool redefine)
4163 {
4164 if (!redefine) {
4165 RDFInternal::CheckValidCppVarName(name, "DefinePerSample");
4166 RDFInternal::CheckForRedefinition("DefinePerSample", name, fColRegister,
4168 } else {
4169 RDFInternal::CheckForDefinition("RedefinePerSample", name, fColRegister,
4171 RDFInternal::CheckForNoVariations("RedefinePerSample", name, fColRegister);
4172 }
4173
4174 auto retTypeName = RDFInternal::TypeID2TypeName(typeid(RetType_t));
4175 if (retTypeName.empty()) {
4176 // The type is not known to the interpreter.
4177 // We must not error out here, but if/when this column is used in jitted code
4178 const auto demangledType = RDFInternal::DemangleTypeIdName(typeid(RetType_t));
4179 retTypeName = "CLING_UNKNOWN_TYPE_" + demangledType;
4180 }
4181
4182 auto newColumn =
4183 std::make_shared<RDFDetail::RDefinePerSample<F>>(name, retTypeName, std::move(expression), *fLoopManager);
4184
4186 newCols.AddDefine(std::move(newColumn));
4187 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newCols));
4188 return newInterface;
4189 }
4190
4191 ////////////////////////////////////////////////////////////////////////////
4192 /// \brief Implementation of DefinePerSample and RedefinePerSample (jitted).
4193 RInterface<Proxied> DefinePerSampleJitImpl(std::string_view name, std::string_view expression, bool redefine)
4194 {
4195 // these checks must be done before jitting lest we throw exceptions in jitted code
4196 if (!redefine) {
4197 RDFInternal::CheckValidCppVarName(name, redefine ? "RedefinePerSample" : "DefinePerSample");
4198 RDFInternal::CheckForRedefinition("DefinePerSample", name, fColRegister,
4200 } else {
4201 RDFInternal::CheckForDefinition("RedefinePerSample", name, fColRegister,
4203 RDFInternal::CheckForNoVariations("RedefinePerSample", name, fColRegister);
4204 }
4205
4206 auto jittedDefine = RDFInternal::BookDefinePerSampleJit(name, expression, *fLoopManager, fColRegister);
4207
4209 newCols.AddDefine(std::move(jittedDefine));
4210
4211 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newCols));
4212
4213 return newInterface;
4214 }
4215
4216 ////////////////////////////////////////////////////////////////////////////
4217 /// \brief Implementation of cache.
4218 template <typename... ColTypes, std::size_t... S>
4219 RInterface<RLoopManager> CacheImpl(const ColumnNames_t &columnList, std::index_sequence<S...>)
4220 {
4221 const auto columnListWithoutSizeColumns = RDFInternal::FilterArraySizeColNames(columnList, "Snapshot");
4222
4223 // Check at compile time that the columns types are copy constructible
4224 constexpr bool areCopyConstructible =
4225 RDFInternal::TEvalAnd<std::is_copy_constructible<ColTypes>::value...>::value;
4226 static_assert(areCopyConstructible, "Columns of a type which is not copy constructible cannot be cached yet.");
4227
4228 RDFInternal::CheckTypesAndPars(sizeof...(ColTypes), columnListWithoutSizeColumns.size());
4229
4230 auto colHolders = std::make_tuple(Take<ColTypes>(columnListWithoutSizeColumns[S])...);
4231 auto ds = std::make_unique<RLazyDS<ColTypes...>>(
4232 std::make_pair(columnListWithoutSizeColumns[S], std::get<S>(colHolders))...);
4233
4234 RInterface<RLoopManager> cachedRDF(std::make_shared<RLoopManager>(std::move(ds), columnListWithoutSizeColumns));
4235
4236 return cachedRDF;
4237 }
4238
4239 template <bool IsSingleColumn, typename F>
4241 VaryImpl(const std::vector<std::string> &colNames, F &&expression, const ColumnNames_t &inputColumns,
4242 const std::vector<std::string> &variationTags, std::string_view variationName)
4243 {
4244 using F_t = std::decay_t<F>;
4245 using ColTypes_t = typename TTraits::CallableTraits<F_t>::arg_types;
4246 using RetType = typename TTraits::CallableTraits<F_t>::ret_type;
4247 constexpr auto nColumns = ColTypes_t::list_size;
4248
4249 SanityChecksForVary<RetType>(colNames, variationTags, variationName);
4250
4251 const auto validColumnNames = GetValidatedColumnNames(nColumns, inputColumns);
4252 CheckAndFillDSColumns(validColumnNames, ColTypes_t{});
4253
4254 auto retTypeName = RDFInternal::TypeID2TypeName(typeid(RetType));
4255 if (retTypeName.empty()) {
4256 // The type is not known to the interpreter, but we don't want to error out
4257 // here, rather if/when this column is used in jitted code, so we inject a broken but telling type name.
4258 const auto demangledType = RDFInternal::DemangleTypeIdName(typeid(RetType));
4259 retTypeName = "CLING_UNKNOWN_TYPE_" + demangledType;
4260 }
4261
4262 auto variation = std::make_shared<RDFInternal::RVariation<F_t, IsSingleColumn>>(
4263 colNames, variationName, std::forward<F>(expression), variationTags, retTypeName, fColRegister, *fLoopManager,
4264 validColumnNames);
4265
4267 newCols.AddVariation(std::move(variation));
4268
4269 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newCols));
4270
4271 return newInterface;
4272 }
4273
4274 RInterface<Proxied> JittedVaryImpl(const std::vector<std::string> &colNames, std::string_view expression,
4275 const std::vector<std::string> &variationTags, std::string_view variationName,
4276 bool isSingleColumn)
4277 {
4278 R__ASSERT(!variationTags.empty() && "Must have at least one variation.");
4279 R__ASSERT(!colNames.empty() && "Must have at least one varied column.");
4280 R__ASSERT(!variationName.empty() && "Must provide a variation name.");
4281
4282 for (auto &colName : colNames) {
4283 RDFInternal::CheckValidCppVarName(colName, "Vary");
4284 RDFInternal::CheckForDefinition("Vary", colName, fColRegister,
4286 }
4287 RDFInternal::CheckValidCppVarName(variationName, "Vary");
4288
4289 // when varying multiple columns, they must be different columns
4290 if (colNames.size() > 1) {
4291 std::set<std::string> uniqueCols(colNames.begin(), colNames.end());
4292 if (uniqueCols.size() != colNames.size())
4293 throw std::logic_error("A column name was passed to the same Vary invocation multiple times.");
4294 }
4295
4296 // Cannot vary different input column types, assume the first
4297 auto varyColType = GetColumnType(colNames[0]);
4298 auto jittedVariation =
4299 RDFInternal::BookVariationJit(colNames, variationName, variationTags, expression, *fLoopManager,
4300 GetDataSource(), fColRegister, isSingleColumn, varyColType);
4301
4303 newColRegister.AddVariation(std::move(jittedVariation));
4304
4305 RInterface<Proxied> newInterface(fProxiedPtr, *fLoopManager, std::move(newColRegister));
4306
4307 return newInterface;
4308 }
4309
4310 template <typename Helper, typename ActionResultType>
4311 auto CallCreateActionWithoutColsIfPossible(const std::shared_ptr<ActionResultType> &resPtr,
4312 const std::shared_ptr<Helper> &hPtr,
4314 -> decltype(hPtr->Exec(0u), RResultPtr<ActionResultType>{})
4315 {
4316 return CreateAction<RDFInternal::ActionTags::Book>(/*columns=*/{}, resPtr, hPtr, fProxiedPtr, 0u);
4317 }
4318
4319 template <typename Helper, typename ActionResultType, typename... Others>
4320 RResultPtr<ActionResultType>
4321 CallCreateActionWithoutColsIfPossible(const std::shared_ptr<ActionResultType> &,
4322 const std::shared_ptr<Helper>& /*hPtr*/,
4323 Others...)
4324 {
4325 throw std::logic_error(std::string("An action was booked with no input columns, but the action requires "
4326 "columns! The action helper type was ") +
4327 typeid(Helper).name());
4328 return {};
4329 }
4330
4331protected:
4332 RInterface(const std::shared_ptr<Proxied> &proxied, RLoopManager &lm,
4333 const RDFInternal::RColumnRegister &colRegister)
4334 : RInterfaceBase(lm, colRegister), fProxiedPtr(proxied)
4335 {
4336 }
4337
4338 const std::shared_ptr<Proxied> &GetProxiedPtr() const { return fProxiedPtr; }
4339};
4340
4341} // namespace RDF
4342
4343} // namespace ROOT
4344
4345#endif // ROOT_RDF_INTERFACE
#define f(i)
Definition RSha256.hxx:104
#define h(i)
Definition RSha256.hxx:106
#define e(i)
Definition RSha256.hxx:103
Basic types used by ROOT and required by TInterpreter.
unsigned int UInt_t
Unsigned integer 4 bytes (unsigned int)
Definition RtypesCore.h:61
long long Long64_t
Portable signed long integer 8 bytes.
Definition RtypesCore.h:84
unsigned long long ULong64_t
Portable unsigned long integer 8 bytes.
Definition RtypesCore.h:85
#define X(type, name)
#define R__ASSERT(e)
Checks condition e and reports a fatal error if it's false.
Definition TError.h:139
void Warning(const char *location, const char *msgfmt,...)
Use this function in warning situations.
Definition TError.cxx:252
winID h TVirtualViewer3D TVirtualGLPainter p
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t dest
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t Int_t Int_t Window_t TString Int_t GCValues_t GetPrimarySelectionOwner GetDisplay GetScreen GetColormap GetNativeEvent const char const char dpyName wid window const char font_name cursor keysym reg const char only_if_exist regb h Point_t winding char text const char depth char const char Int_t count const char ColorStruct_t color const char filename
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void value
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t Int_t Int_t Window_t TString Int_t GCValues_t GetPrimarySelectionOwner GetDisplay GetScreen GetColormap GetNativeEvent const char const char dpyName wid window const char font_name cursor keysym reg const char only_if_exist regb h Point_t winding char text const char depth char const char Int_t count const char ColorStruct_t color const char Pixmap_t Pixmap_t PictureAttributes_t attr const char char ret_data h unsigned char height h Atom_t Int_t ULong_t ULong_t unsigned char prop_list Atom_t Atom_t Atom_t Time_t type
char name[80]
Definition TGX11.cxx:142
Base class for action helpers, see RInterface::Book() for more information.
implementation of FilterAvailable and FilterMissing operations
The head node of a RDF computation graph.
A histogram data structure to bin data along multiple dimensions.
A histogram for aggregation of data along multiple dimensions.
Definition RHist.hxx:66
Helper class that provides the operation graph nodes.
A RDataFrame node that produces a result.
Definition RAction.hxx:53
A binder for user-defined columns, variations and aliases.
std::vector< std::string_view > GenerateColumnNames() const
Return the list of the names of the defined columns (Defines + Aliases).
void AddVariation(std::shared_ptr< RVariationBase > variation)
Register a new systematic variation.
void AddDefine(std::shared_ptr< RDFDetail::RDefineBase > column)
Add a new defined column.
RDFDetail::RDefineBase * GetDefine(std::string_view colName) const
Return the RDefine for the requested column name, or nullptr.
The dataset specification for RDataFrame.
virtual const std::vector< std::string > & GetColumnNames() const =0
Returns a reference to the collection of the dataset's column names.
The base public interface to the RDataFrame federation of classes.
std::string GetColumnType(std::string_view column)
Return the type of a given column as a string.
ColumnNames_t GetValidatedColumnNames(const unsigned int nColumns, const ColumnNames_t &columns)
ColumnNames_t GetColumnTypeNamesList(const ColumnNames_t &columnList)
std::shared_ptr< ROOT::Detail::RDF::RLoopManager > fLoopManager
< The RLoopManager at the root of this computation graph. Never null.
RResultPtr< ActionResultType > CreateAction(const ColumnNames_t &columns, const std::shared_ptr< ActionResultType > &r, const std::shared_ptr< HelperArgType > &helperArg, const std::shared_ptr< RDFNode > &proxiedPtr, const int=-1)
Create RAction object, return RResultPtr for the action Overload for the case in which all column typ...
RDataSource * GetDataSource() const
void CheckAndFillDSColumns(ColumnNames_t validCols, TTraits::TypeList< ColumnTypes... > typeList)
void CheckIMTDisabled(std::string_view callerName)
ColumnNames_t GetColumnNames()
Returns the names of the available columns.
RDFDetail::RLoopManager * GetLoopManager() const
RDFInternal::RColumnRegister fColRegister
Contains the columns defined up to this node.
The public interface to the RDataFrame federation of classes.
RResultPtr< RDisplay > Display(const ColumnNames_t &columnList, size_t nRows=5, size_t nMaxCollectionElements=10)
Provides a representation of the columns in the dataset.
RResultPtr<::TProfile > Profile1D(const TProfile1DModel &model, std::string_view v1Name, std::string_view v2Name, std::string_view wName)
Fill and return a one-dimensional profile (lazy action).
RResultPtr<::THnD > HistoND(const THnDModel &model, const ColumnNames_t &columnList, std::string_view wName="")
Fill and return an N-dimensional histogram (lazy action).
RResultPtr<::TGraph > Graph(std::string_view x="", std::string_view y="")
Fill and return a TGraph object (lazy action).
RInterface< Proxied > Vary(std::string_view colName, F &&expression, const ColumnNames_t &inputColumns, const std::vector< std::string > &variationTags, std::string_view variationName="")
Register systematic variations for a single existing column using custom variation tags.
RInterface< Proxied > Vary(const std::vector< std::string > &colNames, std::string_view expression, std::size_t nVariations, std::string_view variationName)
Register systematic variations for multiple existing columns using auto-generated variation tags.
RResultPtr< ROOT::Experimental::RHist< BinContentType > > Hist(std::uint64_t nNormalBins, std::pair< double, double > interval, std::string_view vName, std::string_view wName)
Fill and return a one-dimensional RHist with weights (lazy action).
RInterface(const RInterface &)=default
Copy-ctor for RInterface.
RResultPtr< RDFDetail::MaxReturnType_t< T > > Max(std::string_view columnName="")
Return the maximum of processed column values (lazy action).
auto CallCreateActionWithoutColsIfPossible(const std::shared_ptr< ActionResultType > &resPtr, const std::shared_ptr< Helper > &hPtr, TTraits::TypeList< RDFDetail::RInferredType >) -> decltype(hPtr->Exec(0u), RResultPtr< ActionResultType >{})
RInterface(RInterface &&)=default
Move-ctor for RInterface.
RInterface< Proxied > Vary(std::string_view colName, std::string_view expression, const std::vector< std::string > &variationTags, std::string_view variationName="")
Register systematic variations for a single existing column using custom variation tags.
RInterface< RDFDetail::RFilter< F, Proxied > > Filter(F f, const std::initializer_list< std::string > &columns)
Append a filter to the call graph.
RInterface< RLoopManager > Cache(std::initializer_list< std::string > columnList)
Save selected columns in memory.
RInterface< Proxied > Vary(std::string_view colName, F &&expression, const ColumnNames_t &inputColumns, std::size_t nVariations, std::string_view variationName="")
Register systematic variations for a single existing column using auto-generated variation tags.
RInterface< Proxied > Vary(std::initializer_list< std::string > colNames, std::string_view expression, std::size_t nVariations, std::string_view variationName)
Register systematic variations for multiple existing columns using auto-generated variation tags.
RResultPtr< RInterface< RLoopManager > > Snapshot(std::string_view treename, std::string_view filename, const ColumnNames_t &columnList, const RSnapshotOptions &options=RSnapshotOptions())
RResultPtr<::TProfile2D > Profile2D(const TProfile2DModel &model, std::string_view v1Name, std::string_view v2Name, std::string_view v3Name, std::string_view wName)
Fill and return a two-dimensional profile (lazy action).
RResultPtr< RInterface< RLoopManager > > Snapshot(std::string_view treename, std::string_view filename, std::string_view columnNameRegexp="", const RSnapshotOptions &options=RSnapshotOptions())
Save selected columns to disk, in a new TTree or RNTuple treename in file filename.
RResultPtr< RDisplay > Display(const ColumnNames_t &columnList, size_t nRows=5, size_t nMaxCollectionElements=10)
Provides a representation of the columns in the dataset.
RResultPtr< RDisplay > Display(std::initializer_list< std::string > columnList, size_t nRows=5, size_t nMaxCollectionElements=10)
Provides a representation of the columns in the dataset.
RInterface(const std::shared_ptr< RLoopManager > &proxied)
Build a RInterface from a RLoopManager.
RResultPtr< ROOT::Experimental::RProfile > Profile(std::shared_ptr< ROOT::Experimental::RProfile > p, const ColumnNames_t &columnList, std::string_view vName)
Fill the provided RProfile (lazy action).
RResultPtr<::THnSparseD > HistoNSparseD(const THnSparseDModel &model, const ColumnNames_t &columnList, std::string_view wName="")
Fill and return a sparse N-dimensional histogram (lazy action).
RInterface< Proxied > Redefine(std::string_view name, F expression, const ColumnNames_t &columns={})
Overwrite the value and/or type of an existing column.
std::shared_ptr< Proxied > fProxiedPtr
Smart pointer to the graph node encapsulated by this RInterface.
RInterface< Proxied > Vary(const std::vector< std::string > &colNames, std::string_view expression, const std::vector< std::string > &variationTags, std::string_view variationName)
Register systematic variations for multiple existing columns using custom variation tags.
RInterface< Proxied > Vary(std::string_view colName, std::string_view expression, std::size_t nVariations, std::string_view variationName="")
Register systematic variations for a single existing column using auto-generated variation tags.
RResultPtr<::TH1D > Histo1D(std::string_view vName)
Fill and return a one-dimensional histogram with the values of a column (lazy action).
RInterface< RDFDetail::RRange< Proxied > > Range(unsigned int begin, unsigned int end, unsigned int stride=1)
Creates a node that filters entries based on range: [begin, end).
RInterface< Proxied > DefinePerSampleImpl(std::string_view name, F expression, bool redefine)
Implementation of DefinePerSample and RedefinePerSample (non-jitted).
RResultPtr< typename std::decay_t< Helper >::Result_t > Book(Helper &&helper, const ColumnNames_t &columns={})
Book execution of a custom action using a user-defined helper object.
RResultPtr< ROOT::Experimental::RHist< BinContentType > > Hist(std::vector< ROOT::Experimental::RAxisVariant > axes, const ColumnNames_t &columnList)
Fill and return an RHist (lazy action).
RResultPtr<::TProfile > Profile1D(const TProfile1DModel &model, std::string_view v1Name="", std::string_view v2Name="")
Fill and return a one-dimensional profile (lazy action).
const std::shared_ptr< Proxied > & GetProxiedPtr() const
RResultPtr<::TH1D > Histo1D(const TH1DModel &model={"", "", 128u, 0., 0.})
Fill and return a one-dimensional histogram with the weighted values of a column (lazy action).
RResultPtr< T > Reduce(F f, std::string_view columnName="")
Execute a user-defined reduce operation on the values of a column.
RResultPtr< double > Median(std::string_view columnName="")
Return the median value of the input column (lazy action).
RResultPtr< T > Reduce(F f, std::string_view columnName, const T &redIdentity)
Execute a user-defined reduce operation on the values of a column.
RInterface< Proxied > Vary(const std::vector< std::string > &colNames, F &&expression, const ColumnNames_t &inputColumns, const std::vector< std::string > &variationTags, std::string_view variationName)
Register systematic variations for multiple existing columns using custom variation tags.
RInterface< RLoopManager > Cache(const ColumnNames_t &columnList)
Save selected columns in memory.
RResultPtr<::TH1D > Histo1D(const TH1DModel &model, std::string_view vName, std::string_view wName)
Fill and return a one-dimensional histogram with the weighted values of a column (lazy action).
RResultPtr< RDisplay > Display(std::string_view columnNameRegexp="", size_t nRows=5, size_t nMaxCollectionElements=10)
Provides a representation of the columns in the dataset.
RInterface & operator=(const RInterface &)=default
Copy-assignment operator for RInterface.
RInterface< Proxied > VaryImpl(const std::vector< std::string > &colNames, F &&expression, const ColumnNames_t &inputColumns, const std::vector< std::string > &variationTags, std::string_view variationName)
RResultPtr<::THnSparseD > HistoNSparseD(const THnSparseDModel &model, const ColumnNames_t &columnList, std::string_view wName="")
Fill and return a sparse N-dimensional histogram (lazy action).
RInterface< Proxied > Define(std::string_view name, std::string_view expression)
Define a new column.
RInterface< RDFDetail::RFilterWithMissingValues< Proxied > > FilterAvailable(std::string_view column)
Discard entries with missing values.
std::enable_if_t<!IsFStringConv &&!IsRetTypeDefConstr, RInterface< Proxied > > DefineImpl(std::string_view, F, const ColumnNames_t &, const std::string &)
RInterface< Proxied > Redefine(std::string_view name, std::string_view expression)
Overwrite the value and/or type of an existing column.
std::vector< std::string > GetFilterNames()
Returns the names of the filters created.
RInterface< RLoopManager > Cache(std::string_view columnNameRegexp="")
Save selected columns in memory.
RResultPtr<::TH1D > Histo1D(const TH1DModel &model={"", "", 128u, 0., 0.}, std::string_view vName="")
Fill and return a one-dimensional histogram with the values of a column (lazy action).
RInterface< Proxied > Vary(std::initializer_list< std::string > colNames, F &&expression, const ColumnNames_t &inputColumns, const std::vector< std::string > &variationTags, std::string_view variationName)
Register systematic variations for multiple existing columns using custom variation tags.
RResultPtr<::TH3D > Histo3D(const TH3DModel &model, std::string_view v1Name, std::string_view v2Name, std::string_view v3Name, std::string_view wName)
Fill and return a three-dimensional histogram (lazy action).
RInterface< Proxied > DefinePerSampleJitImpl(std::string_view name, std::string_view expression, bool redefine)
Implementation of DefinePerSample and RedefinePerSample (jitted).
void LoadValuesCustom(const ColumnNames_t &columnList, const std::vector< std::size_t > &vecSizes, float vecPadding, ROOT::RVecF &dest)
RResultPtr< ROOT::Experimental::RProfile > Profile(std::uint64_t nNormalBins, std::pair< double, double > interval, std::string_view xName, std::string_view vName)
Fill and return a one-dimensional RProfile (lazy action).
friend class RDFInternal::GraphDrawing::GraphCreatorHelper
RResultPtr< ROOT::Experimental::RHistEngine< BinContentType > > Hist(std::shared_ptr< ROOT::Experimental::RHistEngine< BinContentType > > h, const ColumnNames_t &columnList)
Fill the provided RHistEngine (lazy action).
RInterface< RLoopManager > CacheImpl(const ColumnNames_t &columnList, std::index_sequence< S... >)
Implementation of cache.
RResultPtr<::TProfile2D > Profile2D(const TProfile2DModel &model, std::string_view v1Name="", std::string_view v2Name="", std::string_view v3Name="")
Fill and return a two-dimensional profile (lazy action).
RInterface< RDFDetail::RFilter< F, Proxied > > Filter(F f, std::string_view name)
Append a filter to the call graph.
RResultPtr< U > Aggregate(AccFun aggregator, MergeFun merger, std::string_view columnName="")
Execute a user-defined accumulation operation on the processed column values in each processing slot.
RInterface< Proxied > RedefinePerSample(std::string_view name, std::string_view expression)
Redefine an existing column that is updated when the input sample changes.
std::enable_if_t< std::is_default_constructible< RetType >::value, RInterface< Proxied > > DefineImpl(std::string_view name, F &&expression, const ColumnNames_t &columns, const std::string &where)
RResultPtr< ROOT::Experimental::RHist< BinContentType > > Hist(std::shared_ptr< ROOT::Experimental::RHist< BinContentType > > h, const ColumnNames_t &columnList)
Fill the provided RHist (lazy action).
RInterface(const std::shared_ptr< Proxied > &proxied, RLoopManager &lm, const RDFInternal::RColumnRegister &colRegister)
RResultPtr< COLL > Take(std::string_view column="")
Return a collection of values of a column (lazy action, returns a std::vector by default).
RInterface< Proxied > Alias(std::string_view alias, std::string_view columnName)
Allow to refer to a column with a different name.
RResultPtr< ROOT::Experimental::RProfile > Profile(std::vector< ROOT::Experimental::RAxisVariant > axes, const ColumnNames_t &columnList, std::string_view vName, std::string_view wName)
Fill and return an RProfile with weights (lazy action).
RResultPtr< RDFDetail::MinReturnType_t< T > > Min(std::string_view columnName="")
Return the minimum of processed column values (lazy action).
RResultPtr< RInterface< RLoopManager > > Snapshot(std::string_view treename, std::string_view filename, const ColumnNames_t &columnList, const RSnapshotOptions &options=RSnapshotOptions())
Save selected columns to disk, in a new TTree or RNTuple treename in file filename.
RResultPtr< ROOT::Experimental::RHistEngine< BinContentType > > Hist(std::shared_ptr< ROOT::Experimental::RHistEngine< BinContentType > > h, const ColumnNames_t &columnList, std::string_view wName)
Fill the provided RHistEngine with weights (lazy action).
RResultPtr< RCutFlowReport > Report()
Gather filtering statistics.
RResultPtr<::TH3D > Histo3D(const TH3DModel &model)
RResultPtr<::TH3D > Histo3D(const TH3DModel &model, std::string_view v1Name="", std::string_view v2Name="", std::string_view v3Name="")
Fill and return a three-dimensional histogram (lazy action).
RResultPtr<::TH1D > Histo1D(std::string_view vName, std::string_view wName)
Fill and return a one-dimensional histogram with the weighted values of a column (lazy action).
RInterface< Proxied > DefinePerSample(std::string_view name, std::string_view expression)
Define a new column that is updated when the input sample changes.
RInterface< Proxied > DefineSlotEntry(std::string_view name, F expression, const ColumnNames_t &columns={})
Define a new column with a value dependent on the processing slot and the current entry.
RResultPtr< std::decay_t< T > > Fill(T &&model, const ColumnNames_t &columnList)
Return an object of type T on which T::Fill will be called once per event (lazy action).
RInterface< Proxied > DefineSlot(std::string_view name, F expression, const ColumnNames_t &columns={})
Define a new column with a value dependent on the processing slot.
RInterface< RDFDetail::RFilterWithMissingValues< Proxied > > FilterMissing(std::string_view column)
Keep only the entries that have missing values.
RResultPtr< TStatistic > Stats(std::string_view value="")
Return a TStatistic object, filled once per event (lazy action).
RInterface< Proxied > JittedVaryImpl(const std::vector< std::string > &colNames, std::string_view expression, const std::vector< std::string > &variationTags, std::string_view variationName, bool isSingleColumn)
RResultPtr< ROOT::Experimental::RProfile > Profile(std::shared_ptr< ROOT::Experimental::RProfile > p, const ColumnNames_t &columnList, std::string_view vName, std::string_view wName)
Fill the provided RProfile with weights (lazy action).
RInterface< Proxied > DefaultValueFor(std::string_view column, const T &defaultValue)
In case the value in the given column is missing, provide a default value.
RResultPtr< TStatistic > Stats(std::string_view value, std::string_view weight)
Return a TStatistic object, filled once per event (lazy action).
RResultPtr<::TProfile2D > Profile2D(const TProfile2DModel &model)
Fill and return a two-dimensional profile (lazy action).
RInterface< Proxied > RedefineSlot(std::string_view name, F expression, const ColumnNames_t &columns={})
Overwrite the value and/or type of an existing column.
void Foreach(F f, const ColumnNames_t &columns={})
Execute a user-defined function on each entry (instant action).
RResultPtr<::TH2D > Histo2D(const TH2DModel &model, std::string_view v1Name="", std::string_view v2Name="")
Fill and return a two-dimensional histogram (lazy action).
RResultPtr< ActionResultType > CallCreateActionWithoutColsIfPossible(const std::shared_ptr< ActionResultType > &, const std::shared_ptr< Helper > &, Others...)
RInterface< Proxied > Define(std::string_view name, F expression, const ColumnNames_t &columns={})
Define a new column.
void ForeachSlot(F f, const ColumnNames_t &columns={})
Execute a user-defined function requiring a processing slot index on each entry (instant action).
RResultPtr<::TGraphAsymmErrors > GraphAsymmErrors(std::string_view x="", std::string_view y="", std::string_view exl="", std::string_view exh="", std::string_view eyl="", std::string_view eyh="")
Fill and return a TGraphAsymmErrors object (lazy action).
RResultPtr< U > Aggregate(AccFun aggregator, MergeFun merger, std::string_view columnName, const U &aggIdentity)
Execute a user-defined accumulation operation on the processed column values in each processing slot.
RResultPtr< ROOT::Experimental::RProfile > Profile(std::vector< ROOT::Experimental::RAxisVariant > axes, const ColumnNames_t &columnList, std::string_view vName)
Fill and return an RProfile (lazy action).
RResultPtr< ROOT::Experimental::RHist< BinContentType > > Hist(std::shared_ptr< ROOT::Experimental::RHist< BinContentType > > h, const ColumnNames_t &columnList, std::string_view wName)
Fill the provided RHist with weights (lazy action).
RResultPtr<::TProfile > Profile1D(const TProfile1DModel &model)
Fill and return a one-dimensional profile (lazy action).
RResultPtr< RInterface< RLoopManager > > Snapshot(std::string_view treename, std::string_view filename, std::initializer_list< std::string > columnList, const RSnapshotOptions &options=RSnapshotOptions())
Save selected columns to disk, in a new TTree or RNTuple treename in file filename.
RInterface & operator=(RInterface &&)=default
Move-assignment operator for RInterface.
RResultPtr<::TH2D > Histo2D(const TH2DModel &model)
RResultPtr< double > Mean(std::string_view columnName="")
Return the mean of processed column values (lazy action).
RInterface< RDFDetail::RFilter< F, Proxied > > Filter(F f, const ColumnNames_t &columns={}, std::string_view name="")
Append a filter to the call graph.
RInterface< RLoopManager > Cache(const ColumnNames_t &columnList)
Save selected columns in memory.
RInterface< Proxied > DefinePerSample(std::string_view name, F expression)
Define a new column that is updated when the input sample changes.
RInterface< Proxied > Vary(std::initializer_list< std::string > colNames, F &&expression, const ColumnNames_t &inputColumns, std::size_t nVariations, std::string_view variationName)
Register systematic variations for for multiple existing columns using custom variation tags.
RInterface< RDFDetail::RRange< Proxied > > Range(unsigned int end)
Creates a node that filters entries based on range.
RResultPtr< ROOT::Experimental::RProfile > Profile(std::uint64_t nNormalBins, std::pair< double, double > interval, std::string_view xName, std::string_view vName, std::string_view wName)
Fill and return a one-dimensional RProfile with weights (lazy action).
RInterface< Proxied > RedefineSlotEntry(std::string_view name, F expression, const ColumnNames_t &columns={})
Overwrite the value and/or type of an existing column.
RInterface< RDFDetail::RJittedFilter > Filter(std::string_view expression, std::string_view name="")
Append a filter to the call graph.
RResultPtr< ROOT::Experimental::RHist< BinContentType > > Hist(std::uint64_t nNormalBins, std::pair< double, double > interval, std::string_view vName)
Fill and return a one-dimensional RHist (lazy action).
RResultPtr< ROOT::Experimental::RHist< BinContentType > > Hist(std::vector< ROOT::Experimental::RAxisVariant > axes, const ColumnNames_t &columnList, std::string_view wName)
Fill and return an RHist with weights (lazy action).
RResultPtr< ULong64_t > Count()
Return the number of entries processed (lazy action).
RInterface< Proxied > RedefinePerSample(std::string_view name, F expression)
Redefine an existing column that is updated when the input sample changes.
RResultPtr<::TH2D > Histo2D(const TH2DModel &model, std::string_view v1Name, std::string_view v2Name, std::string_view wName)
Fill and return a weighted two-dimensional histogram (lazy action).
RInterface< Proxied > Vary(const std::vector< std::string > &colNames, F &&expression, const ColumnNames_t &inputColumns, std::size_t nVariations, std::string_view variationName)
Register systematic variations for multiple existing columns using auto-generated tags.
RResultPtr<::THnD > HistoND(const THnDModel &model, const ColumnNames_t &columnList, std::string_view wName="")
Fill and return an N-dimensional histogram (lazy action).
RResultPtr< double > StdDev(std::string_view columnName="")
Return the unbiased standard deviation of processed column values (lazy action).
RResultPtr< RDFDetail::SumReturnType_t< T > > Sum(std::string_view columnName="", const RDFDetail::SumReturnType_t< T > &initValue=RDFDetail::SumReturnType_t< T >{})
Return the sum of processed column values (lazy action).
A RDataSource implementation which is built on top of result proxies.
Smart pointer for the return type of actions.
ROOT's RDataFrame offers a modern, high-level interface for analysis of data stored in TTree ,...
typename RemoveFirstParameter< T >::type RemoveFirstParameter_t
TDirectory::TContext keeps track and restore the current directory.
Definition TDirectory.h:89
A TGraph is an object made of two arrays X and Y with npoints each.
Definition TGraph.h:41
@ kAllAxes
Definition TH1.h:126
Statistical variable, defined by its mean and variance (RMS).
Definition TStatistic.h:33
Double_t y[n]
Definition legend1.C:17
Double_t x[n]
Definition legend1.C:17
const std::type_info & TypeName2TypeID(const std::string &name)
Return the type_info associated to a name.
Definition RDFUtils.cxx:98
void ChangeEmptyEntryRange(const ROOT::RDF::RNode &node, std::pair< ULong64_t, ULong64_t > &&newRange)
void ChangeSpec(const ROOT::RDF::RNode &node, ROOT::RDF::Experimental::RDatasetSpec &&spec)
Changes the input dataset specification of an RDataFrame.
const std::vector< std::string > & GetTopLevelFieldNames(const ROOT::RDF::RDataSource &ds)
Definition RDFUtils.cxx:681
std::string TypeID2TypeName(const std::type_info &id)
Returns the name of a type starting from its type_info An empty string is returned in case of failure...
Definition RDFUtils.cxx:212
std::string GetDataSourceLabel(const ROOT::RDF::RNode &node)
std::string PrettyPrintAddr(const void *const addr)
void TriggerRun(ROOT::RDF::RNode node)
Trigger the execution of an RDataFrame computation graph.
void LoadCustomValues(ROOT::RDF::RNode &node, const std::vector< std::string > &cols, const std::vector< std::size_t > &vecSizes, float vecPadding, ROOT::RVecF &dest)
std::string ColumnName2ColumnTypeName(const std::string &colName, TTree *, RDataSource *, RDefineBase *, bool vector2RVec=true)
Return a string containing the type of the given branch.
Definition RDFUtils.cxx:351
void WarnProfile()
Warn once about experimental filling of RProfile.
Definition RDFUtils.cxx:67
void SetTTreeLifeline(ROOT::RDF::RNode &node, std::any lifeline)
std::vector< std::pair< std::uint64_t, std::uint64_t > > GetDatasetGlobalClusterBoundaries(const RNode &node)
Retrieve the cluster boundaries for each cluster in the dataset, across files, with a global offset.
void WarnHist()
Warn once about experimental filling of RHist.
Definition RDFUtils.cxx:55
void ChangeBeginAndEndEntries(const RNode &node, Long64_t begin, Long64_t end)
RInterface<::ROOT::Detail::RDF::RNodeBase > RNode
std::vector< std::string > ColumnNames_t
ROOT type_traits extensions.
void EnableImplicitMT(UInt_t numthreads=0)
Enable ROOT's implicit multi-threading for all objects and methods that provide an internal paralleli...
Definition TROOT.cxx:617
Bool_t IsImplicitMTEnabled()
Returns true if the implicit multi-threading in ROOT is enabled.
Definition TROOT.cxx:673
@ kError
An error.
void DisableImplicitMT()
Disables the implicit multi-threading in ROOT (see EnableImplicitMT).
Definition TROOT.cxx:659
A special bin content type to compute the bin error in weighted filling.
type is TypeList if MustRemove is false, otherwise it is a TypeList with the first type removed
Definition Utils.hxx:158
Tag to let data sources use the native data type when creating a column reader.
Definition Utils.hxx:334
A collection of options to steer the creation of the dataset on disk through Snapshot().
A struct which stores some basic parameters of a TH1D.
A struct which stores some basic parameters of a TH2D.
A struct which stores some basic parameters of a TH3D.
A struct which stores some basic parameters of a THnD.
A struct which stores some basic parameters of a THnSparseD.
A struct which stores some basic parameters of a TProfile.
A struct which stores some basic parameters of a TProfile2D.
Lightweight storage for a collection of types.