ROOT files contain C++ objects that are stored to disk. You can open files when starting ROOT
or within C++
or Python code
In ROOT you can save objects in ROOT files, making these objects “persistent”. Later on, you can read these objects back: the object is reconstructed in memory.
ROOT files often contain columnar data, used for instance by all LHC (Large Hadron Collider) experiments.
Storing an object in a ROOT file and reading it back
Here we will create a new ROOT file, store a histogram, and read it back.
Creating a ROOT file
Use the function
TFile to create or open a ROOT file.
For the second argument, the following options are available:
"RECREATE": create a ROOT file, replacing it if it already exists.
"NEW": create a ROOT file.
"UPDATE": updates the ROOT file.
"READ": opens an existing ROOT file for reading.
Storing an object in a ROOT file
You can save any object, for instance canvases or histograms, into a ROOT file. You can even store your own types.
TFile derives from
TDirectory; use TDirectory::WriteObject() to write an object to a ROOT file.
A copy of the object
myObject is written to the file
In the file, it can be found back under the name
Closing a ROOT file
ROOT will automatically save and close any ROOT files still open when the session ends.
The ROOT file is also saved and closed when deleting / destructing the
Opening and inspecting a ROOT file
Use TFile::Open() to open a ROOT file.
While this operation might return a valid pointer to a
this object might not be able to access data, for instance because ROOT was unable to open the file in the filesystem.
Use TObject::IsZombie() to check whether the ROOT file was successfully opened.
By default, existing objects are not replaced when writing new objects with the same name.
Instead, a new namecycle is created, denoted by
When retrieving the object from the file, ROOT will automatically pick the highest namecycle.
Some objects, such as histograms, automatically register themselves with the current TDirectory (e.g. the last TFile opened): these objects will appear as
OBJ entries, without a namecycle.
See also → Object ownership.
For the particular case of TTree, cycles only store metadata, see Baskets, clusters and the tree header.
Reading an object from a ROOT file
In C++, use the
Get<T>() method to retrieve the objects from a ROOT file.
In Python, objects in the file are accessible as attributes.
MyHist is retrieved from the ROOT file
Storing columnar data in a ROOT file and reading it back
In addition to individual objects, ROOT files can also store tabular datasets, formed by rows and columns. Such datasets are optimized for fast reading of selected columns during an analysis (throughput in the order of GB/s) and for low memory usage by keeping only a few rows in memory.
Tabular datasets in ROOT are actually not just flat tables, but their columns can contain complex nested collections.
In High-Energy Physics, more than one exabyte of data is stored in ROOT’s tabular format.
Writing a columnar dataset with ROOT
RDataFrame provides a method called Snapshot to write a columnar dataset to a ROOT file.
The example below creates a new dataset with 100 rows, with one column
x that contains random numbers, and stores that dataset in a file
Reading a columnar dataset with ROOT
Let’s see now how to read and process the dataset we just wrote, creating a 1D histogram
Besides ROOT files, RDataFrame can also read from other data sources, for example CSV files:
Merging ROOT files with
hadd utility in
$ROOTSYS/bin/hadd to merge ROOT files:
ROOT command line tools
With the ROOT command line tools you can quickly inspect and modify the contents of ROOT files. The most commonly used ones are:
rootls: Lists the content of a ROOT file.
rootcp: Copies objects stored in a ROOT file to another ROOT file.
rootrm: Deletes objects contained in a ROOT file.
rootmv: Moves objects stored in a ROOT file to another ROOT file.
rootmkdir: Creates a “directory” inside a ROOT file.
rootbrowse: Opens a
TBrowserdirectly with the contents of a ROOT file.
rooteventselector: Extracts a range of events of a tree contained in a ROOT file and put them as a new tree in another ROOT file.
rootprint: Plots objects in an image ROOT file.
rootslimtree: Copies trees with a subset of branches from source ROOT files.
-h option to get more information on the available options for the specific ROOT command line tool.
On the system prompt, you can use the ROOT command line tool
rootls to list the contents of a ROOT file.
ROOT object browser
TBrowser you can browse all ROOT objects within a ROOT file.
You can open it with the
rootbrowse command or as part of a ROOT session, instantiating a
The ROOT object browser is displayed.
Figure: ROOT object browser.
Double-click the ROOT file to inspect its content.
Figure: ROOT object browser displaying the content of a ROOT file.
Double-clicking graphical objects displays them in a canvas tab.
Double-clicking files that end with
.C displays them in an editor tab.
Accessing a remote ROOT file
You can read and write a remote ROOT file by specifying its URL to TFile::Open().
Depending on the features of your ROOT installation, the following protocols will be available: