23.7. Reproducible Analysis
Table of Contents
Why Reproducibility Matters
Reproducible analysis means that someone else, or you in six months, can rerun your work and obtain the same results, starting from the same input data. For ROOT analyses this is especially important because studies often evolve over years, involve many small changes, and contribute to published results.
Reproducibility is not only about code. It combines code, configuration, data, software environment, and documentation. The aim is that every analysis step can be traced, understood, and repeated, rather than reconstructed from memory.
A ROOT analysis is reproducible if:
- All inputs (data, configuration, code, environment) are clearly specified.
- All processing steps are automated, not performed manually in interactive sessions.
- Running the documented commands regenerates the same outputs from the same inputs.
Reproducible analysis saves time by reducing confusion about which version of code or which selection was used. It also makes debugging easier, supports collaboration, and is expected in serious scientific work, especially when results might be reviewed or reanalyzed.
From Interactive ROOT to Scripts
Interactive ROOT sessions are ideal for exploration and trying ideas. However, interactive commands typed into the prompt are easy to lose and hard to exactly repeat. To move toward reproducibility, you should convert successful interactive steps into scripts or macros as soon as they become important.
A good pattern is to begin in the ROOT shell or in a C++ or PyROOT notebook and, once a sequence of commands produces a useful plot or value, copy those commands into a macro or source file. That file becomes the authoritative record of how a particular result was produced.
Every figure or numeric result that might enter a document or a report should correspond to a script that can regenerate it. The script should not depend on manual actions that are difficult to repeat or describe, such as clicking in GUIs or manually editing histograms.
Recording the Full Analysis Chain
A ROOT analysis typically consists of several steps, such as converting raw data to ROOT files, skimming or reducing TTrees, applying selections and calibrations, producing histograms, fitting them, and exporting final plots or numbers. Reproducibility requires that the whole chain be encoded and documented, not only the last plotting step.
It is useful to think in terms of transformations of data. Each step reads some input and writes some output, such as a TTree, a set of histograms, or a ROOT file. To be reproducible, each of these transformations must be described by code and configuration that you keep in your project, not only in temporary directories or hand-edited files.
Whenever you manually create intermediate ROOT files or histograms, for example by using the browser and saving objects by hand, consider whether this should be automated instead. If the intermediate data cannot be recreated by running code, then the chain is incomplete and difficult to reproduce if something is lost or needs to change.
Automation and Batch Execution
Automating ROOT analyses means that important steps are run by non-interactive commands. Instead of opening a canvas, drawing histograms, and clicking through options by hand, the analysis should be able to run from start to finish by executing scripts such as ROOT macros, compiled programs, or Python scripts with PyROOT.
This does not prevent interactive exploration, but any step that matters for final results should have an automated counterpart. For example, you might have one script that reads TTrees and fills histograms, another that performs fits, and a final one that formats plots for publication. Each script should be callable from the command line or from ROOT without user interaction.
Batch execution is especially important when running on remote machines or computing clusters. If you can trigger your full analysis with a small number of commands, you can schedule it, track logs, and rerun it whenever input files or configuration change. Interactive workflows with many manual steps are fragile and difficult to move between systems.
Randomness and Seeds
Many ROOT analyses include random processes, such as toy Monte Carlo simulations, resampling, or generation of pseudo-experiments with TRandom or TRandom3. Random numbers can make results differ from one run to another, which is acceptable for exploration but problematic when a specific output must be reproducible.
To control this, you should explicitly set seeds for your random number generators. This ensures that each call sequence produces the same random numbers every time you run the code with the same seed and ROOT version. When you need varied runs, you can change the seed in a controlled way, but for a baseline reproducible analysis you should fix it.
To obtain reproducible random results in ROOT:
- Use a TRandom subclass, such as TRandom3.
- Call
SetSeedwith an explicit integer value at the beginning of your code. - Record the seed value along with other configuration for the analysis.
If you rely on built-in global random generators without setting seeds, or if you change random number generators between runs without recording the details, you may find that you cannot reproduce specific distributions or fitted parameter values exactly, even with the same code and data.
Configuration Files and Input Parameters
Hard-coding analysis parameters directly inside ROOT source files makes it difficult to understand exactly which values were used and to compare different configurations. To improve reproducibility, separate the parameters that define an analysis from the code that implements it.
Typical parameters include selection cuts, binning descriptions, calibration constants, file paths, branches to read, and fit ranges. Keeping them in configuration files or at least in a clearly separated configuration section of your code makes it easier to see what changed between runs and to track analysis variations.
For example, instead of editing numeric literals inside loops across multiple macros, centralize them in a single place or in a simple text-based configuration file that the analysis scripts read at runtime. That way, when you refer to “the version with tighter selection cuts” or “the updated calibration,” you can point to an explicit file that encodes those changes.
Documenting Data and Inputs
Reproducibility requires that the data you analyze can be identified and retrieved. This means you should record exactly which ROOT files were used, where they came from, and, if possible, which versions or production tags they correspond to.
Within your project directory, it is often useful to include a simple description of external datasets. This can be a text or markdown file that lists data sources, filenames or directory paths, and any preprocessing steps applied before they entered your main analysis. For internal datasets, you may also record the commands or scripts that produced them.
If your analysis uses only a subset of available data or applies specific filters at an early stage, document those choices, because they affect the interpretation of the results. It should be possible to check whether new data can be integrated by re-running the same steps or whether a slightly different selection might change conclusions.
Logging, Metadata, and Outputs
When an analysis runs automatically it is helpful to capture logs and metadata that describe what happened. For ROOT analyses, this can include simple text logs printed by std::cout, command line arguments, configuration summaries, and information about software versions.
One practical approach is to write a short summary object to your output ROOT files, for instance as a TNamed or a small TTree, that contains strings with configuration details, git commit identifiers, random seeds, or data tags. When you open the file later, you can inspect this summary and recover how it was produced.
Outputs should be organised so that multiple runs do not overwrite each other silently. Including timestamps, configuration names, or code version identifiers in output file names can help distinguish different analysis variants. This makes it easier to relate a specific plot or ROOT file to the state of the analysis that created it.
Environment and Version Control
ROOT analyses depend on the software environment, including the ROOT version, the compiler, and any external libraries. Different ROOT versions may change default behaviors or algorithms. For reproducibility, you should record which environment you used and ideally rely on a consistent environment when rerunning the analysis.
At the same time, the analysis code itself should be stored in a version-controlled repository. This is closely related to reproducibility, but version control is discussed in a separate chapter about using Git. The key idea is that every set of outputs corresponds to a specific version of the code, and you should be able to return to that version later.
When you combine a controlled environment, such as a stable ROOT installation managed through a package manager or a container, with version-controlled analysis code and clearly documented inputs and configuration, you establish a strong basis for reproducible ROOT analysis that can be sustained and extended over time.
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!