An interface to read from, or write to, a ROOT file, as well as performing other common operations.
Python interface
RFile is a modern, minimal interface to ROOT files with a focus on simplicity. It allows to perform the basic actions of getting objects from a file, putting objects into it and query the file for metadata.
Here is a typical use of RFile:
myHisto = file.Get("myHisto")
print(f"{myHisto.GetName()} has {myHisto.GetNbins()} bins.")
file.Put("myHisto", myHisto)
static std::unique_ptr< RFile > Open(std::string_view path, const ROpenOptions &opts=ROpenOptions())
Opens the file for reading.
static std::unique_ptr< RFile > Recreate(std::string_view path, const RRecreateOptions &opts=RRecreateOptions())
Opens the file for reading/writing, overwriting it if it already exists.
The Put method will raise an error if an object is already present at the given path; if you want to overwrite an existing object use the Overwrite method instead:
file.Overwrite("myHisto", myOtherHisto)
When overwriting, you may specify a title and whether to keep a backup cycle of a potentially-overwritten object. Note that Overwrite will work just like Put if there is no object to overwrite.
file.Overwrite("myHisto", myOtherHisto, "my new histo", createNewCycle = False)
You can iterate the metadata of all objects inside an RFile using the ListKeys method:
for key in file.ListKeys():
print(key.GetBaseName())
if key.GetClassName() == "TH1D":
histo = file.Get(key.GetPath())
histos.append(histo)
ListKeys is recursive by default. If you want non-recursive behavior, you can specify it with a keyword argument:
for key in file.ListKeys("", recursive=False):
print(key.GetBaseName())
See the documentation of ListKeys for more options.
Directories and paths
Objects in an RFile are organized in a hierarchical structure represented by their "path". A path is the string you pass to Get or Put (like in the examples above) and it uses '/' as the directory separator. A directory is useful to group multiple related objects and it can be used alongside ListKeys:
for key in file.ListKeys("myDir"):
print(key.GetPath())
RNTuple
RNTuple may be read from and written to RFile via the appropriate RNTupleReader/RNTupleWriter methods. See the RFile tutorials for examples. For most use cases, however, we recommend the use of RDataFrame to deal with RNTuple (and TTree) data.
TTree
TTree may be read from RFile but not written through it. To write TTree, keep using TFile (or, better if possible, RDataFrame).
Please refer to the documentation of TFile for the details related to how data and executable code can be stored in ROOT files.
When and why should you use RFile
RFile is a modern and minimalistic interface to ROOT files, both local and remote, that can be used instead of TFile when you only need basic Put/Get operations and don't need the more advanced TFile/TDirectory functionalities. It provides:
- a simple interface that makes it easy to do things right and hard to do things wrong;
- more robustness and better error reporting for those operations;
- clearer ownership semantics expressed through the type system.
RFile doesn't cover the entirety of use cases covered by TFile/TDirectory/TDirectoryFile and is not a 1:1 replacement for them. It is meant to simplify the most common use cases by following newer standard C++ practices.
Ownership model
RFile handles ownership via smart pointers, typically std::unique_ptr.
When getting an object from the file (via RFile::Get) you get back a unique copy of the object. Calling Get on the same object twice produces two independent clones of the object. The ownership over that object is solely on the caller and not shared with the RFile. Therefore, the object will remain valid after closing or destroying the RFile that generated it. This also means that any modification done to the object are not reflected to the file automatically: to update the object in the file you need to write it again (via RFile::Overwrite).
RFile::Put and RFile::Overwrite are the way to write objects to the file. Both methods take a const reference to the object to write and don't change the ownership of the object in any way. Calling Put or Overwrite doesn't guarantee that the object is immediately written to the underlying storage: to ensure that, you need to call RFile::Flush (or close the file).
Directories
Even though there is no equivalent of TDirectory in the RFile API, directories are still an existing concept in RFile (since they are a concept in the ROOT binary format). However they are for now only interacted with indirectly, via the use of filesystem-like string-based paths. If you Put an object in an RFile under the path "path/to/object", "object" will be stored under directory "to" which is in turn stored under directory "path". This hierarchy is encoded in the ROOT file itself and it can provide some optimization and/or conveniences when querying objects.
For the most part, it is convenient to think about RFile in terms of a key-value storage where string-based paths are used to refer to arbitrary objects. However, given the hierarchical nature of ROOT files, certain filesystem-like properties are applied to paths, for ease of use: the '/' character is treated specially as the directory separator; multiple '/' in a row are collapsed into one (since RFile doesn't allow directories with empty names).
At the moment, RFile doesn't allow getting directories via Get, nor writing ones via Put (this may change in the future).
Sample usage
Opening an RFile (for writing) and writing an object to it:
auto myObj =
TH1D(
"h",
"h", 10, 0, 1);
rfile->Put(myObj.GetName(), myObj);
1-D histogram with a double per channel (see TH1 documentation)
Opening an RFile (for reading) and reading an object from it:
auto myObj = file->Get<
TH1D>(
"h");
Definition at line 254 of file RFile.hxx.
|
| | ~RFile () |
| |
| void | Close () |
| | Flushes the RFile if needed and closes it, disallowing any further reading or writing.
|
| |
| size_t | Flush () |
| | Writes all objects and the file structure to disk.
|
| |
| template<typename T > |
| std::unique_ptr< T > | Get (std::string_view path) const |
| | Retrieves an object from the file.
|
| |
| std::optional< RKeyInfo > | GetKeyInfo (std::string_view path) const |
| | Retrieves information about the key of object at path, if one exists.
|
| |
| RFileKeyIterable | ListKeys (std::string_view basePath="", std::uint32_t flags=kListObjects|kListRecursive) const |
| | Returns an iterable over all keys of objects and/or directories written into this RFile starting at path basePath (defaulting to include the content of all subdirectories).
|
| |
| template<typename T > |
| void | Overwrite (std::string_view path, const T &obj, std::string_view title, std::uint32_t overwriteFlags=0) |
| | Like Overwrite(std::string_view, const T&, bool) but allows giving a title to the object.
|
| |
| template<typename T > |
| void | Overwrite (std::string_view path, const T &obj, std::uint32_t overwriteFlags=0) |
| | Puts an object into the file, overwriting any previously-existing object at that path.
|
| |
| void | Print (std::ostream &out=std::cout) const |
| | Prints the internal structure of this RFile to the given stream.
|
| |
| template<typename T > |
| void | Put (std::string_view path, const T &obj, std::string_view title="") |
| | Puts object obj into the file, optionally giving it a title.
|
| |
