12.5. Exploring ROOT Files

Table of Contents

`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:

Field	Meaning
Class name	The class of the stored object, for example `TH1F`
Name	The internal ROOT name, for example `hEnergy`
Cycle	The version number after `;`, for example `;1`
Title	The 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:

Level	Example contents
Top-level file	Directories `calib`, `spectra`, maybe trees
`calib` dir	Histogram `hGain`, other calibration objects
`spectra` dir	Histogram `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.

12.5. Exploring ROOT Files

`ls()`

ROOT browser

File structure

Comments

Where to Move