KAHIBARO Bookshelves
Discord Login Register

12.5. Exploring ROOT Files

`ls()`

When you work with ROOT files, you often need to see what is inside them without writing a full program. The simplest tool for this is the ls() method of TFile and TDirectory. It prints a directory listing of the objects stored in the file or directory, together with their class types.

After you have opened a file, for example:

cpp
TFile *f = TFile::Open("data.root");

you can list the contents of the top level of the file with:

cpp
f->ls();

This prints something like:

text
TFile**         data.root
 TFile*         data.root
  KEY: TH1F     hEnergy;1   Energy spectrum
  KEY: TTree    events;1    Event tree
  KEY: TDirectoryFile  calib;1  Calibration

Each entry that appears after KEY: corresponds to a persistent object stored in the file. The printed columns have a specific meaning:

FieldMeaning
Class nameThe class of the stored object, for example TH1F
NameThe internal ROOT name, for example hEnergy
CycleThe version number after ;, for example ;1
TitleThe human readable title string, for example Energy spectrum

The cycle number indicates how many times an object with the same name has been written. ROOT keeps previous versions by incrementing the cycle: hEnergy;1, hEnergy;2, and so on. ls() always shows the latest cycle for each object, but you see the explicit cycle in the printout.

You can also call ls() on subdirectories inside the file. Suppose the listing shows a directory:

text
KEY: TDirectoryFile  calib;1  Calibration

You can get a pointer to that directory and explore it:

cpp
TDirectory *d = (TDirectory*)f->Get("calib");
d->ls();

Now ROOT prints the content of the calib directory, which might contain histograms, graphs, or other subdirectories.

You are not limited to the top-level TFile pointer. If you are already in a directory context, for example after calling:

cpp
f->cd("calib");
gDirectory->ls();

then ls() lists what is in the current directory pointed to by gDirectory.

You can also use ls() from the ROOT prompt without assigning to variables. For instance:

cpp
root [0] TFile f("data.root");
root [1] f.ls();

This is convenient during interactive exploration.

Important rule: Use ls() on TFile or any TDirectory to see which objects (and subdirectories) are available, including their class type, name, and title. This is the quickest way to discover what is stored in a ROOT file before you start writing analysis code.

ROOT browser

The ROOT browser is a graphical interface that lets you explore ROOT files interactively. Instead of typing commands, you can click through files and directories and inspect objects with the mouse.

To open the browser from a ROOT session, use:

cpp
new TBrowser();

This opens a window with two main panels. On the left you see a tree of items, such as the file system, open ROOT files, and objects within those files. On the right you see previews or details of the selected item. If you start ROOT with graphics enabled, you can also use the menu (for example, from the main canvas window) to open a browser, depending on your ROOT installation.

After you have opened a file, either by double clicking it in the left panel or with:

cpp
TFile *f = TFile::Open("data.root");

you will see the file appear in the browser tree. Expanding the file node shows its top level content: histograms, trees, directories, and other objects. Double clicking on a TDirectoryFile node expands it to show its internal structure in the same way.

When you double click on a drawable object, for example a histogram or a graph, the browser automatically opens a canvas and draws it. This is a very convenient way to quickly inspect what the data inside a file looks like without writing any plotting code. For a TTree, double clicking may open a separate tree viewer, which allows you to pick branches, draw distributions, and apply simple cuts interactively.

You can drag and drop objects from the browser into existing canvases or pads in order to overlay them or compare them visually. Many ROOT users rely on the browser for quick inspection of intermediate results, to verify that objects were written correctly, and to discover object names that they then use in macros.

In addition to ROOT files, the browser can show the system directory structure. This lets you navigate to different directories, open more ROOT files, and compare their contents side by side. Within the tree, icons and colors can help you distinguish between files, directories, histograms, trees, and other object types.

The browser does not change what is stored in your files by default. It gives a read interface and a plotting front end. You can combine the browser with the text-based ls() and Get() operations: for example, locate an object name in the browser, then use that name in your macros to programmatically retrieve and process the same object.

Important rule: Use TBrowser for interactive exploration of ROOT files. It allows you to inspect the structure of files, open and visualize objects with a double click, and discover object names and types before writing analysis code.

File structure

ROOT files are organized internally as a hierarchy of directories and objects, similar to a small filesystem stored inside a single file. Understanding this structure helps you design clear output files and makes later analysis easier.

At the top level, a TFile behaves as a root directory. When you create it:

cpp
TFile *f = TFile::Open("analysis.root", "RECREATE");

you start with an empty top-level directory. When you write an object, for example a histogram,

cpp
TH1F *h = new TH1F("hEnergy", "Energy", 100, 0, 10);
h->Write();

it is stored directly in this top-level directory, unless you have changed into a subdirectory. ls() will then show a KEY entry for this histogram.

You can create subdirectories inside the file using mkdir from TFile or TDirectory:

cpp
TDirectory *dCalib = f->mkdir("calib");
TDirectory *dSpectra = f->mkdir("spectra");

These subdirectories appear as TDirectoryFile keys in the top-level listing. To write objects into a subdirectory, you change to it and then write:

cpp
dCalib->cd();
TH1F *hGain = new TH1F("hGain", "Gain constants", 50, 0, 5);
hGain->Write();
dSpectra->cd();
TH1F *hSignal = new TH1F("hSignal", "Signal spectrum", 200, 0, 20);
hSignal->Write();

The file structure now has a tree form:

LevelExample contents
Top-level fileDirectories calib, spectra, maybe trees
calib dirHistogram hGain, other calibration objects
spectra dirHistogram hSignal, other spectra

Using such a hierarchy helps you separate logically different parts of your output, for example calibration constants, final spectra, intermediate histograms, or different analysis stages. When you organize files in this way, later exploration with ls() or the browser becomes much clearer.

Inside each directory, objects are stored by a unique name. When you call Write() without specifying an explicit name, ROOT uses the object’s current name. If an object with the same name already exists in that directory, ROOT creates a new cycle. For example, if you call:

cpp
hSignal->Write();

several times, the file contains hSignal;1, hSignal;2, and so on. Reading the object by name without a cycle, using:

cpp
TH1F *hLast = (TH1F*)dSpectra->Get("hSignal");

returns the latest cycle. Earlier cycles are still stored and can be accessed explicitly:

cpp
TH1F *hOld = (TH1F*)dSpectra->Get("hSignal;1");

The key points of the internal structure are the following: a TFile is a tree of TDirectory objects, each directory holds keys to stored objects, and each key has a name, class, title, and cycle. Object names are used to retrieve objects, while titles serve mainly as human readable descriptions on plots and in listings.

When exploring unfamiliar ROOT files, the typical workflow combines knowledge of this structure with the exploration tools. First, list the top-level using f->ls(). Identify directories and key objects. Second, descend into directories using TDirectory::cd and call ls() there to see the next level. Third, if graphics are available, use the ROOT browser to visualize objects and inspect distributions and trees quickly. This hierarchical understanding also guides how you design your own analysis output files, so that colleagues and your future self can easily find and interpret the content.

Important rule: Think of a ROOT file as a mini filesystem. The TFile is the root directory, TDirectory objects are subdirectories, and stored objects are identified by unique names and cycles inside each directory. Good directory organization makes exploring and reusing ROOT files much easier.

Views: 0

Comments

Please login to add a comment.

Don't have an account? Register now!

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