26#include <nlohmann/json.hpp>
1503 void Exec(unsigned int slot)
1505 fPerThreadResults[slot]++;
1508 // Called at the end of the event loop.
1511 *fFinalResult = std::accumulate(fPerThreadResults.begin(), fPerThreadResults.end(), 0);
1514 // Called by RDataFrame to retrieve the name of this action.
1515 std::string GetActionName() const { return "MyCounter"; }
1519 ROOT::RDataFrame df(10);
1520 ROOT::RDF::RResultPtr<int> resultPtr = df.Book<>(MyCounter{df.GetNSlots()}, {});
1521 // The GetValue call triggers the event loop
1522 std::cout << "Number of processed entries: " << resultPtr.GetValue() << std::endl;
1526See the Book() method for more information and [this tutorial](https://root.cern/doc/master/df018__customActions_8C.html)
1527for a more complete example.
1529#### Injecting arbitrary code in the event loop with Foreach() and ForeachSlot()
1531Foreach() takes a callable (lambda expression, free function, functor...) and a list of columns and
1532executes the callable on the values of those columns for each event that passes all upstream selections.
1533It can be used to perform actions that are not already available in the interface. For example, the following snippet
1534evaluates the root mean square of column "x":
1536// Single-thread evaluation of RMS of column "x" using Foreach
1539df.Foreach([&sumSq, &n](double x) { ++n; sumSq += x*x; }, {"x"});
1540std::cout << "rms of x: " << std::sqrt(sumSq / n) << std::endl;
1542In multi-thread runs, users are responsible for the thread-safety of the expression passed to Foreach():
1543thread will execute the expression concurrently.
1544The code above would need to employ some resource protection mechanism to ensure non-concurrent writing of `rms`; but
1545this is probably too much head-scratch for such a simple operation.
1547ForeachSlot() can help in this situation. It is an alternative version of Foreach() for which the function takes an
1548additional "processing slot" parameter besides the columns it should be applied to. RDataFrame
1549guarantees that ForeachSlot() will invoke the user expression with different `slot` parameters for different concurrent
1550executions (see [Special helper columns: rdfentry_ and rdfslot_](\ref helper-cols) for more information on the slot parameter).
1551We can take advantage of ForeachSlot() to evaluate a thread-safe root mean square of column "x":
1553// Thread-safe evaluation of RMS of column "x" using ForeachSlot
1554ROOT::EnableImplicitMT();
1555const unsigned int nSlots = df.GetNSlots();
1556std::vector<double> sumSqs(nSlots, 0.);
1557std::vector<unsigned int> ns(nSlots, 0);
1559df.ForeachSlot([&sumSqs, &ns](unsigned int slot, double x) { sumSqs[slot] += x*x; ns[slot] += 1; }, {"x"});
1560double sumSq = std::accumulate(sumSqs.begin(), sumSqs.end(), 0.); // sum all squares
1561unsigned int n = std::accumulate(ns.begin(), ns.end(), 0); // sum all counts
1562std::cout << "rms of x: " << std::sqrt(sumSq / n) << std::endl;
1564Notice how we created one `double` variable for each processing slot and later merged their results via `std::accumulate`.
1568### Dataset joins with friend trees
1570Vertically concatenating multiple trees that have the same columns (creating a logical dataset with the same columns and
1571more rows) is trivial in RDataFrame: just pass the tree name and a list of file names to RDataFrame's constructor, or create a TChain
1572out of the desired trees and pass that to RDataFrame.
1574Horizontal concatenations of trees or chains (creating a logical dataset with the same number of rows and the union of the
1575columns of multiple trees) leverages TTree's "friend" mechanism.
1577Simple joins of trees that do not have the same number of rows are also possible with indexed friend trees (see below).
1579To use friend trees in RDataFrame, set up trees with the appropriate relationships and then instantiate an RDataFrame
1585main.AddFriend(&friend, "myFriend");
1588auto df2 = df.Filter("myFriend.MyCol == 42");
1591The same applies for TChains. Columns coming from the friend trees can be referred to by their full name, like in the example above,
1592or the friend tree name can be omitted in case the column name is not ambiguous (e.g. "MyCol" could be used instead of
1593"myFriend.MyCol" in the example above if there is no column "MyCol" in the main tree).
1595\note A common source of confusion is that trees that are written out from a multi-thread Snapshot() call will have their
1596 entries (block-wise) shuffled with respect to the original tree. Such trees cannot be used as friends of the original
1597 one: rows will be mismatched.
1599Indexed friend trees provide a way to perform simple joins of multiple trees over a common column.
1600When a certain entry in the main tree (or chain) is loaded, the friend trees (or chains) will then load an entry where the
1601"index" columns have a value identical to the one in the main one. For example, in Python:
1607# If a friend tree has an index on `commonColumn`, when the main tree loads
1608# a given row, it also loads the row of the friend tree that has the same
1609# value of `commonColumn`
1610aux_tree.BuildIndex("commonColumn")
1612mainTree.AddFriend(aux_tree)
1614df = ROOT.RDataFrame(mainTree)
1617RDataFrame supports indexed friend TTrees from ROOT v6.24 in single-thread mode and from v6.28/02 in multi-thread mode.
1619\anchor other-file-formats
1620### Reading data formats other than ROOT trees
1621RDataFrame can be interfaced with RDataSources. The ROOT::RDF::RDataSource interface defines an API that RDataFrame can use to read arbitrary columnar data formats.
1623RDataFrame calls into concrete RDataSource implementations to retrieve information about the data, retrieve (thread-local) readers or "cursors" for selected columns
1624and to advance the readers to the desired data entry.
1625Some predefined RDataSources are natively provided by ROOT such as the ROOT::RDF::RCsvDS which allows to read comma separated files:
1627auto tdf = ROOT::RDF::FromCSV("MuRun2010B.csv");
1628auto filteredEvents =
1629 tdf.Filter("Q1 * Q2 == -1")
1630 .Define("m", "sqrt(pow(E1 + E2, 2) - (pow(px1 + px2, 2) + pow(py1 + py2, 2) + pow(pz1 + pz2, 2)))");
1631auto h = filteredEvents.Histo1D("m");
1635See also FromNumpy (Python-only), FromRNTuple(), FromArrow(), FromSqlite().
1638### Computation graphs (storing and reusing sets of transformations)
1640As we saw, transformed dataframes can be stored as variables and reused multiple times to create modified versions of the dataset. This implicitly defines a **computation graph** in which
1641several paths of filtering/creation of columns are executed simultaneously, and finally aggregated results are produced.
1643RDataFrame detects when several actions use the same filter or the same defined column, and **only evaluates each
1644filter or defined column once per event**, regardless of how many times that result is used down the computation graph.
1645Objects read from each column are **built once and never copied**, for maximum efficiency.
1646When "upstream" filters are not passed, subsequent filters, temporary column expressions and actions are not evaluated,
1647so it might be advisable to put the strictest filters first in the graph.
1649\anchor representgraph
1650### Visualizing the computation graph
1651It is possible to print the computation graph from any node to obtain a [DOT (graphviz)](https://en.wikipedia.org/wiki/DOT_(graph_description_language)) representation either on the standard output
1654Invoking the function ROOT::RDF::SaveGraph() on any node that is not the head node, the computation graph of the branch
1655the node belongs to is printed. By using the head node, the entire computation graph is printed.
1657Following there is an example of usage:
1659// First, a sample computational graph is built
1660ROOT::RDataFrame df("tree", "f.root");
1662auto df2 = df.Define("x", []() { return 1; })
1663 .Filter("col0 % 1 == col0")
1664 .Filter([](int b1) { return b1 <2; }, {"cut1"})
1665 .Define("y", []() { return 1; });
1667auto count = df2.Count();
1669// Prints the graph to the rd1.dot file in the current directory
1670ROOT::RDF::SaveGraph(df, "./mydot.dot");
1671// Prints the graph to standard output
1672ROOT::RDF::SaveGraph(df);
1675The generated graph can be rendered using one of the graphviz filters, e.g. `dot`. For instance, the image below can be generated with the following command:
1677$ dot -Tpng computation_graph.dot -ocomputation_graph.png
1680\image html RDF_Graph2.png
1683### Activating RDataFrame execution logs
1685RDataFrame has experimental support for verbose logging of the event loop runtimes and other interesting related information. It is activated as follows:
1687#include <ROOT/RLogger.hxx>
1689// this increases RDF's verbosity level as long as the `verbosity` variable is in scope
1690auto verbosity = ROOT::RLogScopedVerbosity(ROOT::Detail::RDF::RDFLogChannel(), ROOT::ELogLevel::kInfo);
1697verbosity = ROOT.RLogScopedVerbosity(ROOT.Detail.RDF.RDFLogChannel(), ROOT.ELogLevel.kInfo)
1700More information (e.g. start and end of each multi-thread task) is printed using `ELogLevel.kDebug` and even more
1701(e.g. a full dump of the generated code that RDataFrame just-in-time-compiles) using `ELogLevel.kDebug+10`.
1703\anchor rdf-from-spec
1704### Creating an RDataFrame from a dataset specification file
1706RDataFrame can be created using a dataset specification JSON file:
1711df = ROOT.RDF.Experimental.FromSpec("spec.json")
1714The input dataset specification JSON file needs to be provided by the user and it describes all necessary samples and
1715their associated metadata information. The main required key is the "samples" (at least one sample is needed) and the
1716required sub-keys for each sample are "trees" and "files". Additionally, one can specify a metadata dictionary for each
1717sample in the "metadata" key.
1719A simple example for the formatting of the specification in the JSON file is the following:
1725 "trees": ["tree1", "tree2"],
1726 "files": ["file1.root", "file2.root"],
1730 "sample_category" = "data"
1734 "trees": ["tree3", "tree4"],
1735 "files": ["file3.root", "file4.root"],
1739 "sample_category" = "MC_background"
1746The metadata information from the specification file can be then accessed using the DefinePerSample function.
1747For example, to access luminosity information (stored as a double):
1750df.DefinePerSample("lumi", 'rdfsampleinfo_.GetD("lumi")')
1753or sample_category information (stored as a string):
1756df.DefinePerSample("sample_category", 'rdfsampleinfo_.GetS("sample_category")')
1759or directly the filename:
1762df.DefinePerSample("name", "rdfsampleinfo_.GetSampleName()")
1765An example implementation of the "FromSpec" method is available in tutorial: df106_HiggstoFourLeptons.py, which also
1766provides a corresponding exemplary JSON file for the dataset specification.
1769### Adding a progress bar
1771A progress bar showing the processed event statistics can be added to any RDataFrame program.
1772The event statistics include elapsed time, currently processed file, currently processed events, the rate of event processing
1773and an estimated remaining time (per file being processed). It is recorded and printed in the terminal every m events and every
1774n seconds (by default m = 1000 and n = 1). The ProgressBar can be also added when the multithread (MT) mode is enabled.
1776ProgressBar is added after creating the dataframe object (df):
1778ROOT::RDataFrame df("tree", "file.root");
1779ROOT::RDF::Experimental::AddProgressBar(df);
1782Alternatively, RDataFrame can be cast to an RNode first, giving the user more flexibility
1783For example, it can be called at any computational node, such as Filter or Define, not only the head node,
1784with no change to the ProgressBar function itself (please see the [Python interface](classROOT_1_1RDataFrame.html#python)
1785section for appropriate usage in Python):
1787ROOT::RDataFrame df("tree", "file.root");
1788auto df_1 = ROOT::RDF::RNode(df.Filter("x>1"));
1789ROOT::RDF::Experimental::AddProgressBar(df_1);
1791Examples of implemented progress bars can be seen by running [Higgs to Four Lepton tutorial](https://root.cern/doc/master/df106__HiggsToFourLeptons_8py_source.html) and [Dimuon tutorial](https://root.cern/doc/master/df102__NanoAODDimuonAnalysis_8C.html).
1793\anchor missing-values
1794### Working with missing values in the dataset
1796In certain situations a dataset might be missing one or more values at one or
1797more of its entries. For example:
1799- If the dataset is composed of multiple files and one or more files is
1800 missing one or more columns required by the analysis.
1801- When joining different datasets horizontally according to some index value
1802 (e.g. the event number), if the index does not find a match in one or more
1803 other datasets for a certain entry.
1804- If, for a certain event, a column is invalid because it results from a Snapshot
1805 with systematic variations, and that variation didn't pass its filters. For
1806 more details, see \ref snapshot-with-variations.
1808For example, suppose that column "y" does not have a value for entry 42:
1818If the RDataFrame application reads that column, for example if a Take() action
1819was requested, the default behaviour is to throw an exception indicating
1820that that column is missing an entry.
1822The following paragraphs discuss the functionalities provided by RDataFrame to
1823work with missing values in the dataset.
1825#### FilterAvailable and FilterMissing
1827FilterAvailable and FilterMissing are specialized RDataFrame Filter operations.
1828They take as input argument the name of a column of the dataset to watch for
1829missing values. Like Filter, they will either keep or discard an entire entry
1830based on whether a condition returns true or false. Specifically:
1832- FilterAvailable: the condition is whether the value of the column is present.
1833 If so, the entry is kept. Otherwise if the value is missing the entry is
1835- FilterMissing: the condition is whether the value of the column is missing. If
1836 so, the entry is kept. Otherwise if the value is present the entry is
1840df = ROOT.RDataFrame(dataset)
1842# Anytime an entry from "col" is missing, the entire entry will be filtered out
1843df_available = df.FilterAvailable("col")
1844df_available = df_available.Define("twice", "col * 2")
1846# Conversely, if we want to select the entries for which the column has missing
1847# values, we do the following
1848df_missingcol = df.FilterMissing("col")
1849# Following operations in the same branch of the computation graph clearly
1850# cannot access that same column, since there would be no value to read
1851df_missingcol = df_missingcol.Define("observable", "othercolumn * 2")
1855ROOT::RDataFrame df{dataset};
1857// Anytime an entry from "col" is missing, the entire entry will be filtered out
1858auto df_available = df.FilterAvailable("col");
1859auto df_twicecol = df_available.Define("twice", "col * 2");
1861// Conversely, if we want to select the entries for which the column has missing
1862// values, we do the following
1863auto df_missingcol = df.FilterMissing("col");
1864// Following operations in the same branch of the computation graph clearly
1865// cannot access that same column, since there would be no value to read
1866auto df_observable = df_missingcol.Define("observable", "othercolumn * 2");
1871DefaultValueFor creates a node of the computation graph which just forwards the
1872values of the columns necessary for other downstream nodes, when they are
1873available. In case a value of the input column passed to this function is not
1874available, the node will provide the default value passed to this function call
1878df = ROOT.RDataFrame(dataset)
1879# Anytime an entry from "col" is missing, the value will be the default one
1880default_value = ... # Some sensible default value here
1881df = df.DefaultValueFor("col", default_value)
1882df = df.Define("twice", "col * 2")
1886ROOT::RDataFrame df{dataset};
1887// Anytime an entry from "col" is missing, the value will be the default one
1888constexpr auto default_value = ... // Some sensible default value here
1889auto df_default = df.DefaultValueFor("col", default_value);
1890auto df_col = df_default.Define("twice", "col * 2");
1893#### Mixing different strategies to work with missing values in the same RDataFrame
1895All the operations presented above only act on the particular branch of the
1896computation graph where they are called, so that different results can be
1897obtained by mixing and matching the filtering or providing a default value
1901df = ROOT.RDataFrame(dataset)
1902# Anytime an entry from "col" is missing, the value will be the default one
1903default_value = ... # Some sensible default value here
1904df_default = df.DefaultValueFor("col", default_value).Define("twice", "col * 2")
1905df_filtered = df.FilterAvailable("col").Define("twice", "col * 2")
1907# Same number of total entries as the input dataset, with defaulted values
1908df_default.Display(["twice"]).Print()
1909# Only keep the entries where "col" has values
1910df_filtered.Display(["twice"]).Print()
1914ROOT::RDataFrame df{dataset};
1916// Anytime an entry from "col" is missing, the value will be the default one
1917constexpr auto default_value = ... // Some sensible default value here
1918auto df_default = df.DefaultValueFor("col", default_value).Define("twice", "col * 2");
1919auto df_filtered = df.FilterAvailable("col").Define("twice", "col * 2");
1921// Same number of total entries as the input dataset, with defaulted values
1922df_default.Display({"twice"})->Print();
1923// Only keep the entries where "col" has values
1924df_filtered.Display({"twice"})->Print();
1927#### Further considerations
1929Note that working with missing values is currently supported with a TTree-based
1930data source. Support of this functionality for other data sources may come in
1933\anchor special-values
1934### Dealing with NaN or Inf values in the dataset
1936RDataFrame does not treat NaNs or infinities beyond what the floating-point standards require, i.e. they will
1937propagate to the final result.
1938Non-finite numbers can be suppressed using Filter(), e.g.:
1941df.Filter("std::isfinite(x)").Mean("x")
1944\anchor rosetta-stone
1945### Translating TTree commands to RDataFrame
1953 <b>ROOT::RDataFrame</b>
1959// Get the tree and Draw a histogram of x for selected y values
1960auto *tree = file->Get<TTree>("myTree");
1961tree->Draw("x", "y > 2");
1966ROOT::RDataFrame df("myTree", file);
1967df.Filter("y > 2").Histo1D("x")->Draw();
1974// Draw a histogram of "jet_eta" with the desired weight
1975tree->Draw("jet_eta", "weight*(event == 1)");
1980df.Filter("event == 1").Histo1D("jet_eta", "weight")->Draw();
1987// Draw a histogram filled with values resulting from calling a method of the class of the `event` branch in the TTree.
1988tree->Draw("event.GetNtrack()");
1994df.Define("NTrack","event.GetNtrack()").Histo1D("NTrack")->Draw();
2001// Draw only every 10th event
2002tree->Draw("fNtrack","fEvtHdr.fEvtNum%10 == 0");
2007// Use the Filter operation together with the special RDF column: `rdfentry_`
2008df.Filter("rdfentry_ % 10 == 0").Histo1D("fNtrack")->Draw();
2015// object selection: for each event, fill histogram with array of selected pts
2016tree->Draw('Muon_pt', 'Muon_pt > 100');
2021// with RDF, arrays are read as ROOT::VecOps::RVec objects
2022df.Define("good_pt", "Muon_pt[Muon_pt > 100]").Histo1D("good_pt")->Draw();
2030// Draw the histogram and fill hnew with it
2031tree->Draw("sqrt(x)>>hnew","y>0");
2033// Retrieve hnew from the current directory
2034auto hnew = gDirectory->Get<TH1F>("hnew");
2039// We pass histogram constructor arguments to the Histo1D operation, to easily give the histogram a name
2040auto hist = df.Define("sqrt_x", "sqrt(x)").Filter("y>0").Histo1D({"hnew","hnew", 10, 0, 10}, "sqrt_x");
2047// Draw a 1D Profile histogram instead of TH2F
2048tree->Draw("y:x","","prof");
2050// Draw a 2D Profile histogram instead of TH3F
2051tree->Draw("z:y:x","","prof");
2057// Draw a 1D Profile histogram
2058df.Profile1D("x", "y")->Draw();
2060// Draw a 2D Profile histogram
2061df.Profile2D("x", "y", "z")->Draw();
2068// This command draws 2 entries starting with entry 5
2069tree->Draw("x", "","", 2, 5);
2074// Range function with arguments begin, end
2075df.Range(5,7).Histo1D("x")->Draw();
2082// Draw the X() component of the
2083// ROOT::Math::DisplacementVector3D in vec_list
2084tree->Draw("vec_list.X()");
2089df.Define("x", "ROOT::RVecD out; for(const auto &el: vec_list) out.push_back(el.X()); return out;").Histo1D("x")->Draw();
2096// Gather all values from a branch holding a collection per event, `pt`,
2097// and fill a histogram so that we can count the total number of values across all events
2098tree->Draw("pt>>histo");
2099auto histo = gDirectory->Get<TH1D>("histo");
2105df.Histo1D("pt")->GetEntries();
2111 <b>TTree::Scan()</b>
2114 <b>ROOT::RDataFrame</b>
2120// Print a table of the first 10 entries for all variables in the Tree
2121// if the first entry in the Muon_pt collection is > 10.
2122tree->Scan("*", "Muon_pt[0] > 10.", "", 10);
2127// Selecting columns using a regular expression
2128df.Filter("Muon_pt[0] > 10.").Display(".*", 10)->Print();
2135// For 10 events, print Muon_pt and Muon_eta, starting at entry 100
2136tree->Scan("Muon_pt:Muon_eta", "", "", 10, 100);
2141// Selecting columns using a collection of names
2142df.Range(100, 0).Display({"Muon_pt", "Muon_eta"}, 10)->Print();
2269namespace Experimental {
2323 auto *
lm = df->GetLoopManager();
2325 throw std::runtime_error(
"Cannot print information about this RDataFrame, "
2326 "it was not properly created. It must be discarded.");
2328 auto defCols =
lm->GetDefaultColumnNames();
2330 std::ostringstream
ret;
2331 if (
auto ds = df->GetDataSource()) {
2332 ret <<
"A data frame associated to the data source \"" << cling::printValue(
ds) <<
"\"";
2334 ret <<
"An empty data frame that will create " <<
lm->GetNEmptyEntries() <<
" entries\n";
Basic types used by ROOT and required by TInterpreter.
unsigned long long ULong64_t
Portable unsigned long integer 8 bytes.
ROOT::Detail::TRangeCast< T, true > TRangeDynCast
TRangeDynCast is an adapter class that allows the typed iteration through a TCollection.
The head node of a RDF computation graph.
The dataset specification for RDataFrame.
ROOT's RDataFrame offers a modern, high-level interface for analysis of data stored in TTree ,...
RDataFrame(std::string_view treeName, std::string_view filenameglob, const ColumnNames_t &defaultColumns={})
Build the dataframe.
ROOT::RDF::ColumnNames_t ColumnNames_t
Describe directory structure in memory.
A TTree represents a columnar dataset.
ROOT::RDF::Experimental::RDatasetSpec RetrieveSpecFromJson(const std::string &jsonFile)
Function to retrieve RDatasetSpec from JSON file provided.
ROOT::RDataFrame FromSpec(const std::string &jsonFile)
Factory method to create an RDataFrame from a JSON specification file.
std::vector< std::string > ColumnNames_t
std::shared_ptr< const ColumnNames_t > ColumnNamesPtr_t
