Logo ROOT  
Reference Guide
RDFHelpers.hxx
Go to the documentation of this file.
1// Author: Enrico Guiraud, Danilo Piparo CERN 02/2018
2
3/*************************************************************************
4 * Copyright (C) 1995-2018, 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// This header contains helper free functions that slim down RDataFrame's programming model
12
13#ifndef ROOT_RDF_HELPERS
14#define ROOT_RDF_HELPERS
15
19#include <ROOT/RResultHandle.hxx> // users of RunGraphs might rely on this transitive include
20#include <ROOT/TypeTraits.hxx>
21
22#include <fstream>
23#include <functional>
24#include <memory>
25#include <type_traits>
26#include <utility> // std::index_sequence
27#include <vector>
28
29namespace ROOT {
30namespace Internal {
31namespace RDF {
32template <typename... ArgTypes, typename F>
34{
35 return std::function<bool(ArgTypes...)>([=](ArgTypes... args) mutable { return !f(args...); });
36}
37
38template <typename... ArgTypes, typename Ret, typename... Args>
40{
41 return std::function<bool(ArgTypes...)>([=](ArgTypes... args) mutable { return !f(args...); });
42}
43
44template <typename I, typename T, typename F>
46
47template <std::size_t... N, typename T, typename F>
48class PassAsVecHelper<std::index_sequence<N...>, T, F> {
49 template <std::size_t Idx>
50 using AlwaysT = T;
51 std::decay_t<F> fFunc;
52
53public:
54 PassAsVecHelper(F &&f) : fFunc(std::forward<F>(f)) {}
55 auto operator()(AlwaysT<N>... args) -> decltype(fFunc({args...})) { return fFunc({args...}); }
56};
57
58template <std::size_t N, typename T, typename F>
60{
61 return PassAsVecHelper<std::make_index_sequence<N>, T, F>(std::forward<F>(f));
62}
63
64} // namespace RDF
65} // namespace Internal
66
67namespace RDF {
69
70// clag-format off
71/// Given a callable with signature bool(T1, T2, ...) return a callable with same signature that returns the negated result
72///
73/// The callable must have one single non-template definition of operator(). This is a limitation with respect to
74/// std::not_fn, required for interoperability with RDataFrame.
75// clang-format on
76template <typename F,
77 typename Args = typename ROOT::TypeTraits::CallableTraits<std::decay_t<F>>::arg_types_nodecay,
78 typename Ret = typename ROOT::TypeTraits::CallableTraits<std::decay_t<F>>::ret_type>
79auto Not(F &&f) -> decltype(RDFInternal::NotHelper(Args(), std::forward<F>(f)))
80{
81 static_assert(std::is_same<Ret, bool>::value, "RDF::Not requires a callable that returns a bool.");
82 return RDFInternal::NotHelper(Args(), std::forward<F>(f));
83}
84
85// clang-format off
86/// PassAsVec is a callable generator that allows passing N variables of type T to a function as a single collection.
87///
88/// PassAsVec<N, T>(func) returns a callable that takes N arguments of type T, passes them down to function `func` as
89/// an initializer list `{t1, t2, t3,..., tN}` and returns whatever f({t1, t2, t3, ..., tN}) returns.
90///
91/// Note that for this to work with RDataFrame the type of all columns that the callable is applied to must be exactly T.
92/// Example usage together with RDataFrame ("varX" columns must all be `float` variables):
93/// \code
94/// bool myVecFunc(std::vector<float> args);
95/// df.Filter(PassAsVec<3, float>(myVecFunc), {"var1", "var2", "var3"});
96/// \endcode
97// clang-format on
98template <std::size_t N, typename T, typename F>
100{
102}
103
104// clang-format off
105/// Create a graphviz representation of the dataframe computation graph, return it as a string.
106/// \param[in] node any node of the graph. Called on the head (first) node, it prints the entire graph. Otherwise, only the branch the node belongs to.
107///
108/// The output can be displayed with a command akin to `dot -Tpng output.dot > output.png && open output.png`.
109///
110/// Note that "hanging" Defines, i.e. Defines without downstream nodes, will not be displayed by SaveGraph as they are
111/// effectively optimized away from the computation graph.
112///
113/// Note that SaveGraph is not thread-safe and must not be called concurrently from different threads.
114// clang-format on
115template <typename NodeType>
116std::string SaveGraph(NodeType node)
117{
119 return helper.RepresentGraph(node);
120}
121
122// clang-format off
123/// Create a graphviz representation of the dataframe computation graph, write it to the specified file.
124/// \param[in] node any node of the graph. Called on the head (first) node, it prints the entire graph. Otherwise, only the branch the node belongs to.
125/// \param[in] outputFile file where to save the representation.
126///
127/// The output can be displayed with a command akin to `dot -Tpng output.dot > output.png && open output.png`.
128///
129/// Note that "hanging" Defines, i.e. Defines without downstream nodes, will not be displayed by SaveGraph as they are
130/// effectively optimized away from the computation graph.
131///
132/// Note that SaveGraph is not thread-safe and must not be called concurrently from different threads.
133// clang-format on
134template <typename NodeType>
135void SaveGraph(NodeType node, const std::string &outputFile)
136{
138 std::string dotGraph = helper.RepresentGraph(node);
139
140 std::ofstream out(outputFile);
141 if (!out.is_open()) {
142 throw std::runtime_error("Could not open output file \"" + outputFile + "\"for reading");
143 }
144
145 out << dotGraph;
146 out.close();
147}
148
149// clang-format off
150/// Cast a RDataFrame node to the common type ROOT::RDF::RNode
151/// \param[in] node Any node of a RDataFrame graph
152// clang-format on
153template <typename NodeType>
154RNode AsRNode(NodeType node)
155{
156 return node;
157}
158
159// clang-format off
160/// Trigger the event loop of multiple RDataFrames concurrently
161/// \param[in] handles A vector of RResultHandles
162///
163/// This function triggers the event loop of all computation graphs which relate to the
164/// given RResultHandles. The advantage compared to running the event loop implicitly by accessing the
165/// RResultPtr is that the event loops will run concurrently. Therefore, the overall
166/// computation of all results is generally more efficient.
167/// It should be noted that user-defined operations (e.g., Filters and Defines) of the different RDataFrame graphs are assumed to be safe to call concurrently.
168///
169/// ~~~{.cpp}
170/// ROOT::RDataFrame df1("tree1", "file1.root");
171/// auto r1 = df1.Histo1D("var1");
172///
173/// ROOT::RDataFrame df2("tree2", "file2.root");
174/// auto r2 = df2.Sum("var2");
175///
176/// // RResultPtr -> RResultHandle conversion is automatic
177/// ROOT::RDF::RunGraphs({r1, r2});
178/// ~~~
179// clang-format on
180void RunGraphs(std::vector<RResultHandle> handles);
181
182namespace Experimental {
183
184/// \brief Produce all required systematic variations for the given result.
185/// \param[in] resPtr The result for which variations should be produced.
186/// \return A \ref ROOT::RDF::Experimental::RResultMap "RResultMap" object with full variation names as strings
187/// (e.g. "pt:down") and the corresponding varied results as values.
188///
189/// A given input RResultPtr<T> produces a corresponding RResultMap<T> with a "nominal"
190/// key that will return a value identical to the one contained in the original RResultPtr.
191/// Other keys correspond to the varied values of this result, one for each variation
192/// that the result depends on.
193/// VariationsFor does not trigger the event loop. The event loop is only triggered
194/// upon first access to a valid key, similarly to what happens with RResultPtr.
195///
196/// If the result does not depend, directly or indirectly, from any registered systematic variation, the
197/// returned RResultMap will contain only the "nominal" key.
198///
199/// See RDataFrame's \ref ROOT::RDF::RInterface::Vary() "Vary" method for more information and example usages.
200///
201/// \note Currently, producing variations for the results of \ref ROOT::RDF::RInterface::Display() "Display",
202/// \ref ROOT::RDF::RInterface::Report() "Report" and \ref ROOT::RDF::RInterface::Snapshot() "Snapshot"
203/// actions is not supported.
204//
205// An overview of how systematic variations work internally. Given N variations (including the nominal):
206//
207// RResultMap owns RVariedAction
208// N results N action helpers
209// N previous filters
210// N*#input_cols column readers
211//
212// ...and each RFilter and RDefine knows for what universe it needs to construct column readers ("nominal" by default).
213template <typename T>
215{
216 R__ASSERT(resPtr != nullptr && "Calling VariationsFor on an empty RResultPtr");
217
218 // populate parts of the computation graph for which we only have "empty shells", e.g. RJittedActions and
219 // RJittedFilters
220 resPtr.fLoopManager->Jit();
221
222 std::unique_ptr<RDFInternal::RActionBase> variedAction;
223 std::vector<std::shared_ptr<T>> variedResults;
224
225 std::shared_ptr<RDFInternal::RActionBase> nominalAction = resPtr.fActionPtr;
226 std::vector<std::string> variations = nominalAction->GetVariations();
227 const auto nVariations = variations.size();
228
229 if (nVariations > 0) {
230 // clone the result once for each variation
231 variedResults.reserve(nVariations);
232 for (auto i = 0u; i < nVariations; ++i)
233 // implicitly assuming that T is copiable: this should be the case
234 // for all result types in use, as they are copied for each slot
235 variedResults.emplace_back(new T{*resPtr.fObjPtr});
236
237 std::vector<void *> typeErasedResults;
238 typeErasedResults.reserve(variedResults.size());
239 for (auto &res : variedResults)
240 typeErasedResults.emplace_back(&res);
241
242 // Create the RVariedAction and inject it in the computation graph.
243 // This recursively creates all the required varied column readers and upstream nodes of the computation graph.
244 variedAction = nominalAction->MakeVariedAction(std::move(typeErasedResults));
245 }
246
247 return RDFInternal::MakeResultMap<T>(resPtr.fObjPtr, std::move(variedResults), std::move(variations),
248 *resPtr.fLoopManager, std::move(nominalAction), std::move(variedAction));
249}
250
251} // namespace Experimental
252} // namespace RDF
253} // namespace ROOT
254#endif
#define f(i)
Definition: RSha256.hxx:104
#define R__ASSERT(e)
Definition: TError.h:118
#define N
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void value
TRObject operator()(const T1 &t1) const
void Jit()
Add RDF nodes that require just-in-time compilation to the computation graph.
std::string RepresentGraph(ROOT::RDataFrame &rDataFrame)
Starting from the root node, prints the entire graph.
The public interface to the RDataFrame federation of classes.
Definition: RInterface.hxx:103
Smart pointer for the return type of actions.
Definition: RResultPtr.hxx:103
RDFDetail::RLoopManager * fLoopManager
Non-owning pointer to the RLoopManager at the root of this computation graph.
Definition: RResultPtr.hxx:154
std::shared_ptr< RDFInternal::RActionBase > fActionPtr
Owning pointer to the action that will produce this result.
Definition: RResultPtr.hxx:158
SPT_t fObjPtr
Shared pointer encapsulating the wrapped result.
Definition: RResultPtr.hxx:155
#define F(x, y, z)
std::function< bool(ArgTypes...)> NotHelper(ROOT::TypeTraits::TypeList< ArgTypes... >, Ret(*f)(Args...))
Definition: RDFHelpers.hxx:39
std::function< bool(ArgTypes...)> NotHelper(ROOT::TypeTraits::TypeList< ArgTypes... >, F &&f)
Definition: RDFHelpers.hxx:33
auto PassAsVec(F &&f) -> PassAsVecHelper< std::make_index_sequence< N >, T, F >
Definition: RDFHelpers.hxx:59
double T(double x)
Definition: ChebyshevPol.h:34
RResultMap< T > VariationsFor(RResultPtr< T > resPtr)
Produce all required systematic variations for the given result.
Definition: RDFHelpers.hxx:214
auto PassAsVec(F &&f) -> RDFInternal::PassAsVecHelper< std::make_index_sequence< N >, T, F >
PassAsVec is a callable generator that allows passing N variables of type T to a function as a single...
Definition: RDFHelpers.hxx:99
void RunGraphs(std::vector< RResultHandle > handles)
Trigger the event loop of multiple RDataFrames concurrently.
Definition: RDFHelpers.cxx:29
auto Not(F &&f) -> decltype(RDFInternal::NotHelper(Args(), std::forward< F >(f)))
Given a callable with signature bool(T1, T2, ...) return a callable with same signature that returns ...
Definition: RDFHelpers.hxx:79
std::string SaveGraph(NodeType node)
Create a graphviz representation of the dataframe computation graph, return it as a string.
Definition: RDFHelpers.hxx:116
RNode AsRNode(NodeType node)
Cast a RDataFrame node to the common type ROOT::RDF::RNode.
Definition: RDFHelpers.hxx:154
void function(const Char_t *name_, T fun, const Char_t *docstring=0)
Definition: RExports.h:167
This file contains a specialised ROOT message handler to test for diagnostic in unit tests.
void forward(const LAYERDATA &prevLayerData, LAYERDATA &currLayerData)
apply the weights (and functions) in forward direction of the DNN
Definition: NeuralNet.icc:546
Lightweight storage for a collection of types.
Definition: TypeTraits.hxx:25