18.1. Introduction to RDataFrame
Table of Contents
Why RDataFrame?
RDataFrame is a high level interface in ROOT that lets you analyze columnar data in a clear, compact, and declarative way. Instead of writing long C++ event loops that manually read branches, apply selections, and fill histograms, you describe what you want to compute and RDataFrame builds and executes the processing pipeline for you.
The central idea is that a TTree or a similar dataset is treated as a table. Each branch is a column, each entry is a row, and you define operations on columns. Typical operations are filtering rows, defining new columns from existing ones, and creating histograms or other statistics from selected columns. RDataFrame takes care of looping over the data efficiently in the background.
You usually create a RDataFrame from a TTree or directly from a ROOT file. Conceptually it looks like this:
ROOT::RDataFrame df("Events", "data.root");
auto df_selected = df.Filter("energy > 1.0", "Energy cut");
auto df_with_var = df_selected.Define("p2", "px*px + py*py + pz*pz");
auto h_energy = df_selected.Histo1D("energy");
auto h_p2 = df_with_var.Histo1D("p2");Here you never write an explicit event loop. You describe a chain of operations that starts from a dataset called "Events" in the file "data.root". The expression strings refer directly to branch names or previously defined columns.
RDataFrame is especially useful in analyses where you want to iterate on your selection and definitions many times. The code is shorter and easier to read, so it is simpler to modify cuts, add new variables, and produce new histograms as your analysis evolves.
Another key feature is that RDataFrame can transparently use multiple CPU cores. The same analysis code can run single threaded or multithreaded. When ROOT implicit multithreading is enabled, RDataFrame automatically splits the dataset among threads and merges the results at the end. This is particularly important for large datasets that are typical in particle and nuclear physics.
RDataFrame is not limited to TTrees on disk. You can also use it with chains of trees, with datasets in memory, and with different types of backends. For a beginner working with ROOT, it provides a modern and consistent way to do data analysis that is closer to concepts from data frames in other environments, while still using all the ROOT classes and file formats.
RDataFrame lets you write analysis code without explicit event loops. You describe operations on columns, and RDataFrame handles the looping, filtering, and histogram filling internally, with optional automatic multithreading.
RDataFrame vs traditional TTree loops
Traditional ROOT analysis code is usually written as an explicit event loop over a TTree. In that style, you open a file, get a TTree, set branch addresses, then write a for loop that calls GetEntry for each event, applies if statements for cuts, and fills histograms manually.
Conceptually, a simple traditional loop looks like this:
TFile *f = TFile::Open("data.root");
TTree *t = (TTree*)f->Get("Events");
float energy;
t->SetBranchAddress("energy", &energy);
TH1F h("h_energy", "Energy", 100, 0, 10);
Long64_t nEntries = t->GetEntries();
for (Long64_t i = 0; i < nEntries; ++i) {
t->GetEntry(i);
if (energy > 1.0) {
h.Fill(energy);
}
}The same operation with RDataFrame is much more compact:
ROOT::RDataFrame df("Events", "data.root");
auto h_energy = df.Filter("energy > 1.0").Histo1D("energy");In both cases you open the same file, use the same branch, and fill a histogram with the same selection. The difference is in how you express the analysis.
Traditional TTree loops are imperative. You tell the computer step by step how to do the work: get this entry, read these branches, check this condition, then fill that histogram. You are responsible for all control flow.
RDataFrame is declarative. You describe what operations should be performed on columns: filter by this condition, define this new quantity, then build this histogram. The control flow is hidden, and RDataFrame decides how to process the data efficiently.
This difference has several practical consequences. RDataFrame code is typically shorter and easier to read. You can modify cuts and definitions in a single place without changing a long loop. The analysis steps are captured as a chain of transformations on a dataset, which matches how physicists often think about analysis: starting with raw events, applying selections, computing derived quantities, and finally producing results.
Another important difference is how RDataFrame handles performance and scheduling. In a traditional loop, you must manually enable multithreading, manage thread safe objects, and control how entries are distributed. With RDataFrame, multithreading is built in. Once ROOT implicit multithreading is enabled, the same RDataFrame script can run on multiple cores. The framework splits the dataset into ranges, processes them in parallel, and combines results at the end.
Traditional loops also tend to spread analysis logic across many lines of code. Selection cuts, variable definitions, and histogram filling can be interleaved with technical details such as branch address setup. With RDataFrame, selections and definitions are tied directly to the dataset in a linear chain of calls. This helps keep analysis and technical details better separated.
Despite these advantages, RDataFrame does not replace all uses of traditional loops. If you need very custom control over entry access, complex state machines across events, or highly optimized specialized code, a manual loop can still be useful. RDataFrame is designed for common analysis workflows where you operate on events independently, which covers most physics analyses at the level of histograms and derived quantities.
When comparing both styles, remember that the underlying data structures are the same. RDataFrame still reads TTrees and uses ROOT I/O. The difference is the programming model. As you progress in this course, you will see that many of the tasks that would require explicit branches, loops, and histogram management can be expressed more clearly with RDataFrame, while still allowing you to use all your existing knowledge of ROOT classes and C++.
Views: 0
Where to Move
Move chapter:
- ☰ 1. Introduction to ROOT
- ☰ 1.1. What Is ROOT?
- ☰ 1.2. Installing ROOT
- ☰ 1.3. Starting ROOT
- ☰ 1.4. Your First ROOT Session
-
- ☰ 2. C++ Basics for ROOT
- ☰ 2.1. Why ROOT Uses C++
- ☰ 2.2. Variables and Data Types
- ☰ 2.3. Operators
- ☰ 2.4. Conditional Statements
- ☰ 2.5. Loops
- ☰ 2.6. Functions
- ☰ 2.7. Arrays and Vectors
-
- ☰ 3. ROOT Macros
- ☰ 3.1. What Is a ROOT Macro?
- ☰ 3.2. Running ROOT Macros
- ☰ 3.3. Functions Inside ROOT Macros
- ☰ 3.4. Compiling ROOT Macros
- ☰ 3.5. Organizing a ROOT Project
-
- ☰ 4. ROOT Objects and the ROOT Object Model
- ☰ 4.1. Introduction to ROOT Classes
- ☰ 4.2. Object Names and Titles
- ☰ 4.3. ROOT Collections
- ☰ 4.4. Inspecting ROOT Objects
-
- ☰ 5. Histograms
- ☰ 5.1. Introduction to Histograms
- ☰ 5.2. Creating a 1D Histogram
- ☰ 5.3. Filling Histograms
- ☰ 5.4. Drawing Histograms
- ☰ 5.5. Histogram Properties
- ☰ 5.6. Accessing Histogram Bins
- ☰ 5.7. Histogram Errors
- ☰ 5.8. Normalizing Histograms
- ☰ 5.9. Combining Histograms
-
- ☰ 6. Two-Dimensional Histograms
- ☰ 6.1. Creating 2D Histograms
- ☰ 6.2. Filling 2D Histograms
- ☰ 6.3. Drawing 2D Histograms
- ☰ 6.4. Projections
- ☰ 6.5. Profiles
-
- ☰ 7. Graphs
- ☰ 7.1. Introduction to TGraph
- ☰ 7.2. Creating a TGraph
- ☰ 7.3. Graph Styling
- ☰ 7.4. TGraphErrors
- ☰ 7.5. TGraphAsymmErrors
- ☰ 7.6. MultiGraph
-
- ☰ 8. Canvases and Plotting
- ☰ 8.1. TCanvas
- ☰ 8.2. Dividing a Canvas
- ☰ 8.3. Drawing Multiple Objects
- ☰ 8.4. Legends
- ☰ 8.5. Text and Annotations
- ☰ 8.6. Logarithmic Axes
- ☰ 8.7. Saving Plots
-
- ☰ 9. Styling ROOT Plots
- ☰ 9.1. ROOT Plot Styles
- ☰ 9.2. Axis Configuration
- ☰ 9.3. Line Styles
- ☰ 9.4. Marker Styles
- ☰ 9.5. Publication-Quality Figures
-
- ☰ 10. Mathematical Functions
- ☰ 10.1. Introduction to TF1
- ☰ 10.2. Built-in Functions
- ☰ 10.3. Custom Functions
- ☰ 10.4. Evaluating Functions
- ☰ 10.5. Function Integrals
-
- ☰ 11. Curve Fitting
- ☰ 11.1. Introduction to Fitting
- ☰ 11.2. Gaussian Fits
- ☰ 11.3. Polynomial Fits
- ☰ 11.4. Custom Fit Functions
- ☰ 11.5. Fit Parameters
- ☰ 11.6. Goodness of Fit
- ☰ 11.7. Fit Residuals
- ☰ 11.8. Fitting Graphs
-
- ☰ 12. ROOT Files
- ☰ 12.1. Introduction to ROOT Files
- ☰ 12.2. Creating ROOT Files
- ☰ 12.3. Writing Objects
- ☰ 12.4. Reading ROOT Files
- ☰ 12.5. Exploring ROOT Files
- ☰ 12.6. Directories Inside ROOT Files
-
- ☰ 13. TTrees
- ☰ 13.1. Introduction to TTrees
- ☰ 13.2. Creating a TTree
- ☰ 13.3. Filling a TTree
- ☰ 13.4. Writing a TTree to a File
- ☰ 13.5. Reading a TTree
- ☰ 13.6. Inspecting TTrees
- ☰ 13.7. Drawing Data from TTrees
- ☰ 13.8. Applying Selection Cuts
- ☰ 13.9. Branch Addresses
-
- ☰ 14. Event-Based Data Analysis
- ☰ 14.1. Understanding Event Data
- ☰ 14.2. Event Loops
- ☰ 14.3. Event Selection
- ☰ 14.4. Derived Quantities
- ☰ 14.5. Analysis Workflow
-
- ☰ 15. Working with Real Experimental Data
- ☰ 15.1. Importing Text Data
- ☰ 15.2. Converting Data to ROOT
- ☰ 15.3. Data Cleaning
- ☰ 15.4. Data Calibration
- ☰ 15.5. Signal and Background
-
- ☰ 16. Random Numbers and Simulations
- ☰ 16.1. Random Number Generation
- ☰ 16.2. Common Distributions
- ☰ 16.3. Simple Monte Carlo Simulation
- ☰ 16.4. Detector Resolution Simulation
- ☰ 16.5. Efficiency Simulation
-
- ☰ 17. Statistical Analysis with ROOT
- ☰ 17.1. Basic Statistics
- ☰ 17.2. Probability Distributions
- ☰ 17.3. Statistical Uncertainties
- ☰ 17.4. Chi-Square Tests
- ☰ 17.5. Confidence Intervals
-
- ☰ 18. Modern ROOT with RDataFrame
- ☰ 18.1. Introduction to RDataFrame
- ☰ 18.2. Loading Data
- ☰ 18.3. Filtering Data
- ☰ 18.4. Defining New Columns
- ☰ 18.5. Creating Histograms
- ☰ 18.6. Statistical Operations
- ☰ 18.7. Saving Results
- ☰ 18.8. Multithreading
-
- ☰ 19. ROOT and Python
- ☰ 19.1. Introduction to PyROOT
- ☰ 19.2. ROOT Objects in Python
- ☰ 19.3. Reading ROOT Files with Python
- ☰ 19.4. PyROOT and NumPy
- ☰ 19.5. PyROOT and Matplotlib
- ☰ 19.6. Choosing Between C++ and Python
-
- ☰ 20. Advanced TTree Techniques
- ☰ 20.1. Trees with Multiple Branches
- ☰ 20.2. Storing std::vector Objects
- ☰ 20.3. TChain
- ☰ 20.4. Friends
- ☰ 20.5. Efficient TTree Analysis
-
- ☰ 21. ROOT for Particle and Nuclear Physics
- ☰ 21.1. Four-Vectors
- ☰ 21.2. Particle Kinematics
- ☰ 21.3. Invariant Mass
- ☰ 21.4. Angular Distributions
- ☰ 21.5. Detector Spectra
-
- ☰ 22. Debugging and Common ROOT Problems
- ☰ 22.1. ROOT Object Ownership
- ☰ 22.2. Null Pointers
- ☰ 22.3. Segmentation Faults
- ☰ 22.4. Missing Histograms
- ☰ 22.5. ROOT File Problems
- ☰ 22.6. TTree Branch Problems
- ☰ 22.7. Histogram Range Problems
- ☰ 22.8. Fit Failures
- ☰ 22.9. Debugging ROOT Macros
-
- ☰ 23. Writing Better ROOT Analysis Code
- ☰ 23.1. Separating Analysis and Plotting
- ☰ 23.2. Using Functions
- ☰ 23.3. Using Header Files
- ☰ 23.4. Naming Conventions
- ☰ 23.5. Avoiding Hard-Coded Values
- ☰ 23.6. Configuration Parameters
- ☰ 23.7. Reproducible Analysis
- ☰ 23.8. Version Control with Git
-
- ☰ 24. Final Project
- ☰ 24.1. Project Overview
- ☰ 24.2. Analyze a complete scientific dataset using ROOT.
- ☰ 24.3. Import the Data
- ☰ 24.4. Explore the Dataset
- ☰ 24.5. Apply Data Selection
- ☰ 24.6. Create Histograms
- ☰ 24.7. Fit the Data
- ☰ 24.8. Calculate Physical Quantities
- ☰ 24.9. Estimate Statistical Uncertainties
- ☰ 24.10. Create Publication-Quality Figures
- ☰ 24.11. Save the Analysis Results
- ☰ 24.12. Write a Short Analysis Report
-
- ☰ 25. Appendices
- ☰ 25.1. A. ROOT Command Cheat Sheet
- ☰ 25.2. B. ROOT Histogram Classes
- ☰ 25.3. C. ROOT Graph Classes
- ☰ 25.4. D. Common TTree Commands
- ☰ 25.5. E. Common Drawing Options
- ☰ 25.6. F. Common Fit Functions
- ☰ 25.7. G. ROOT C++ Cheat Sheet
- ☰ 25.8. H. PyROOT Cheat Sheet
- ☰ 25.9. I. Common ROOT Errors and Solutions
- ☰ 25.10. J. Recommended ROOT Analysis Workflow
-
Comments
Please login to add a comment.
Don't have an account? Register now!