ROOT I/O¶
The uproot.rootio
module contains everything needed to navigate through a ROOT file and extract inert, data-only objects. Methods for those objects are defined in other modules. The uproot.open
function returns a ROOTDirectory
object, which is a handle into the file, from which all other data can be accessed.
This module has many more classes than those documented here, but all but a few are considered internal details. The classes documented below represent the public API. In fact, only ROOTDirectory
has useful attributes and methods for a typical user. The other two, ROOTObject
and ROOTStreamedObject
, are documented because they are superclasses of all objects that could be extracted from a ROOT file, and may be useful in isinstance
checks.
uproot.rootio.ROOTDirectory¶
Although ROOTDirectory
resembles ROOT’s TFile, TDirectory, and TFileDirectory to some degree, it does not have a direct relationship to any of them. (This is because we adopted a different model for representing the contents of a ROOT file: purely acyclic with continuation passing.) As a result, ROOTDirectory
is not a ROOTObject
and isn’t named “TFile.”
A ROOTDirectory
may represent a whole ROOT file or a single TDirectory within that file— after reading, there is no difference.
-
class
uproot.rootio.
ROOTDirectory
(name, context, keys)¶ Represents a ROOT file or directory, an entry point for reading objects.
Although this class has a constructor that could be called by a user, objects are usually created from ROOT files through
open
orxrootd
.ROOTDirectory
objects may be accessed as Python containers:- square brackets (
__getitem__
) read objects from the file by key name (seeget
). - the
len
function (__len__
) returns the number of keys. - iteration (
__iter__
) iterates over the names of the keys only (like adict
, seekeys
).
Attributes, properties, and methods:
- name (bytes) name of the file or directory as read from the ROOT file. (ROOT files may be imprinted with a different name than they have in the file system.)
- compression (
Compression
) the compression algorithm and level specified in the file header. (Some objects, including TTree branches, may have different compression settings than the global file settings.) get
read an object from the file, selected by name.iterkeys
iterate over key names in this directory.itervalues
iterate over objects in this directory.iteritems
iterate over (key name, object) pairs in this directory, like adict
.iterclasses
iterate over (key name, class object) pairs in this directory.keys
return key names in this directory.values
return objects in this directory.items
return (key name, object) pairs in this directory, like adict
.classes
return (key name, class object) pairs in this directory.allkeys
return keys at all levels of depth (shortcut for passingrecursive=True
tokeys
).allvalues
return objects at all levels of depth (shortcut for passingrecursive=True
tovalues
).allitems
return (key name, object) pairs at all levels of depth (shortcut for passingrecursive=True
toitems
).allclasses
return (key name, class object) pairs at all levels of depth (shortcut for passingrecursive=True
toclasses
).
- square brackets (
-
ROOTDirectory.
get
(name, cycle=None)¶ Read an object from the ROOT file or directory by name.
Parameters: - name (str (str)) – name of the object. Any text before a “
/
” is interpreted as a subdirectory, and subdirectories of any depth may be searched. A number after a “;
” indicates a TKey <uproot.rootio.TKey> cycle. - cycle (
None
or int) – TKey <uproot.rootio.TKey> cycle number to disambiguate keys of the same name. This argument overrides a number after a “;
”.
Returns: a freshly read object from the ROOT file.
Return type: Notes
This method, without the
cycle
argument, can be accessed more directly through square brackets (__getitem__
) on theROOTDirectory
object.- name (str (str)) – name of the object. Any text before a “
-
ROOTDirectory.
iterkeys
(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)¶ Iterate over key names in this directory.
This method does not read objects.
Parameters: - recursive (bool) – if
False
(default), only iterate over this directory level; ifTrue
, depth-first iterate over all subdirectories as well. - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: names of objects and subdirectories in the file.
Return type: iterator over bytes
Notes
This method can be accessed more directly by simply iterating over a
ROOTDirectory
object.- recursive (bool) – if
-
ROOTDirectory.
itervalues
(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)¶ Iterate over objects in this directory.
Parameters: - recursive (bool) – if
False
(default), only iterate over this directory level; ifTrue
, depth-first iterate over all subdirectories as well. - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: freshly read objects from the ROOT file.
Return type: iterator over
ROOTStreamedObject
- recursive (bool) – if
-
ROOTDirectory.
iteritems
(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)¶ Iterate over (key name, object) pairs in this directory, like a
dict
.Parameters: - recursive (bool) – if
False
(default), only iterate over this directory level; ifTrue
, depth-first iterate over all subdirectories as well. - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: name-object pairs from the file.
Return type: iterator over (bytes,
ROOTStreamedObject
)- recursive (bool) – if
-
ROOTDirectory.
iterclasses
(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)¶ Iterate over (key name, class object) pairs in this directory.
This method does not read objects.
Parameters: - recursive (bool) – if
False
(default), only iterate over this directory level; ifTrue
, depth-first iterate over all subdirectories as well. - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: name-class object pairs from the file.
Return type: iterator over (bytes, class object)
- recursive (bool) – if
-
ROOTDirectory.
keys
(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)¶ Return key names in this directory.
This method does not read objects.
Parameters: - recursive (bool) – if
False
(default), only iterate over this directory level; ifTrue
, depth-first iterate over all subdirectories as well. - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: names of objects and subdirectories in the file.
Return type: list of bytes
- recursive (bool) – if
-
ROOTDirectory.
values
(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)¶ Return objects in this directory.
Parameters: - recursive (bool) – if
False
(default), only iterate over this directory level; ifTrue
, depth-first iterate over all subdirectories as well. - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: freshly read objects from the ROOT file.
Return type: list of
ROOTStreamedObject
- recursive (bool) – if
-
ROOTDirectory.
items
(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)¶ Return (key name, object) pairs in this directory, like a
dict
.Parameters: - recursive (bool) – if
False
(default), only iterate over this directory level; ifTrue
, depth-first iterate over all subdirectories as well. - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: name-object pairs from the file.
Return type: list of (bytes,
ROOTStreamedObject
)- recursive (bool) – if
-
ROOTDirectory.
classes
(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)¶ Return (key name, class object) pairs in this directory.
This method does not read objects.
Parameters: - recursive (bool) – if
False
(default), only iterate over this directory level; ifTrue
, depth-first iterate over all subdirectories as well. - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: name-class object pairs from the file.
Return type: list of (bytes, class object)
- recursive (bool) – if
-
ROOTDirectory.
allkeys
(filtername=<function nofilter>, filterclass=<function nofilter>)¶ Return keys at all levels of depth (shortcut for passing
recursive=True
tokeys
).This method does not read objects.
Parameters: - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: names of objects and subdirectories in the file.
Return type: list of bytes
- filtername (function: str ⇒ bool) – only keys for which
-
ROOTDirectory.
allvalues
(filtername=<function nofilter>, filterclass=<function nofilter>)¶ Return objects at all levels of depth (shortcut for passing
recursive=True
tovalues
).Parameters: - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: freshly read objects from the ROOT file.
Return type: list of
ROOTStreamedObject
- filtername (function: str ⇒ bool) – only keys for which
-
ROOTDirectory.
allitems
(filtername=<function nofilter>, filterclass=<function nofilter>)¶ Return (key name, object) pairs at all levels of depth (shortcut for passing
recursive=True
toitems
).Parameters: - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: name-object pairs from the file.
Return type: list of (bytes,
ROOTStreamedObject
)- filtername (function: str ⇒ bool) – only keys for which
-
ROOTDirectory.
allclasses
(filtername=<function nofilter>, filterclass=<function nofilter>)¶ Return (key name, class object) pairs at all levels of depth (shortcut for passing
recursive=True
toclasses
).This method does not read objects.
Parameters: - filtername (function: str ⇒ bool) – only keys for which
filtername(name)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. - filterclass (function: class object ⇒ bool) – only keys for which
filterclass(class object)
returnsTrue
are returned (does not eliminate subdirectories ifrecursive=True
). Default returnsTrue
for all input. Note that all class objects passed to this function have aclassname
attribute for the C++ class name (may differ from the Python class name for syntactic reasons).
Returns: name-class object pairs from the file.
Return type: list of (bytes, class object)
- filtername (function: str ⇒ bool) – only keys for which
uproot.rootio.ROOTObject¶
-
class
uproot.rootio.
ROOTObject
¶ Superclass of all objects read out of a ROOT file (except
ROOTDirectory
).If a
ROOTObject
is not aROOTStreamedObject
, then its class definition is hard-coded, not derived from the file’s streamer info.
uproot.rootio.ROOTStreamedObject¶
-
class
uproot.rootio.
ROOTStreamedObject
¶ Superclass of all objects read out of a ROOT file with an automatically generated class, derived from the file’s streamer info.
Each subclass of a
ROOTStreamedObject
has aclassversion
attribute, corresponding to the class version in the streamer info. If this version does not match the version of the serialized class, an error is raised during the read.