# TTree Handling¶

TTree and TBranch are two of the data objects that are versioned and streamed from ROOT files (subclasses of ROOTStreamedObject). As such, their classes do not exist until observed in a ROOT file, and different class objects may be generated by different versions of the class with different member variables.

However, you may use TTrees and TBranches consistently across versions because they inherit from mix-ins TTreeMethods and TBranchMethods. These interfaces provide more Pythonic names for TTree/TBranch private data and a variety of data-reading routines.

TLeaf and its subclasses do not (currently) have mix-ins: they are used only for their data. TBasket does not even have an instantiation— TBasket bytes are read directly into arrays.

These bytes are read according to some Interpretation, which governs how the bytes are interpreted (source) and what kinds of objects are filled (destination). For numerical data, the source is usually one big-endian array per basket and the destination is usually one native-endian array per branch. You have complete freedom to set the Interpretation for each branch, but sensible defaults are provided (by the interpret function, automatically).

Many of the TTreeMethods and TBranchMethods have the same parameters— identical parameter names have identical meanings. In the documentation below, the definitions are repeated for each method (because it may be the first you call help on, though it inflates the size of this page.).

## uproot.tree.TTreeMethods¶

Every class read from a ROOT file named “TTree” is mixed in with TTreeMethods so that the following methods are available.

class uproot.tree.TTreeMethods

Adds array reading methods to TTree objects that have been streamed from a ROOT file.

• square brackets (__getitem__) returns a branch by name (see get).
• the len function (__len__) returns the number of entries (same as numentries).
• iteration (__iter__) has no implementation. This is to avoid confusion between iterating over all branches (probably not what you want, but fitting the pattern set by ROOTDirectory and dict) and iterating over the data.

Attributes, properties, and methods:

### branch accessors¶

TTreeMethods.get(name, recursive=True, filtername=<function nofilter>, filtertitle=<function nofilter>, aliases=True)

Return a branch by name (at any level of depth).

Parameters: name (str) – name of the branch to return. selected branch. TBranch

Notes

This method can be accessed more directly through square brackets (__getitem__) on the TTree object.

TTreeMethods.iterkeys(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>, aliases=True)

Iterate over branch names.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. names of branches. iterator over bytes
TTreeMethods.itervalues(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Iterate over branches.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. branches. iterator over TBranch
TTreeMethods.iteritems(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>, aliases=True)

Iterate over (branch name, branch) pairs.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. name-branch pairs. iterator over (bytes, TBranch)
TTreeMethods.keys(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>, aliases=True)

Return branch names.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. names of branches. list of bytes
TTreeMethods.values(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Return branches.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. branches. list of TBranch
TTreeMethods.items(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>, aliases=True)

Return (branch name, branch) pairs.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. name-branch pairs. list of (bytes, TBranch)
TTreeMethods.allkeys(filtername=<function nofilter>, filtertitle=<function nofilter>, aliases=True)

Return branch names at all levels of depth (shortcut for passing recursive=True to keys).

Parameters: filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. names of branches. list of bytes
TTreeMethods.allvalues(filtername=<function nofilter>, filtertitle=<function nofilter>)

Return branches at all levels of depth (shortcut for passing recursive=True to values).

Parameters: filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. branches. list of TBranch
TTreeMethods.allitems(filtername=<function nofilter>, filtertitle=<function nofilter>, aliases=True)

Return (branch name, branch) pairs at all levels of depth (shortcut for passing recursive=True to items).

Parameters: filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. name-branch pairs. list of (bytes, TBranch
TTreeMethods.clusters(branches=None, entrystart=None, entrystop=None, strict=False)

Return (int, int) pairs representing cluster entry starts and stops in this TTree.

Todo

Not implemented.

Returns: start (inclusive) and stop (exclusive) pairs for each cluster. list of (int, int)

### array¶

TTreeMethods.array(branch, interpretation=None, entrystart=None, entrystop=None, flatten=False, cache=None, basketcache=None, keycache=None, executor=None, blocking=True)

Read one branch into an array (or other object if provided an alternate interpretation).

Parameters: branch (str) – name of the branch to read. interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. entrystart (None or int) – entry at which reading starts (inclusive). If None (default), start at the beginning of the branch. entrystop (None or int) – entry at which reading stops (exclusive). If None (default), stop at the end of the branch. flatten (bool) – if True (not default), convert JaggedArrays into flat Numpy arrays. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. executor (concurrent.futures.Executor) – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. blocking (bool) – if True (default), do not exit this function until the arrays are read, and return those arrays. If False, exit immediately and return a zero-argument function. That zero-argument function returns the desired array, and it blocks until the array is available. This option is only useful with a non-None executor. array or other object, depending on interpretation.

### lazyarray¶

TTreeMethods.lazyarray(branch, interpretation=None, limitbytes=1048576, cache=None, basketcache=None, keycache=None, executor=None)

Create a lazy array that would read the branch as needed.

Parameters: branch (str) – name of the branch to read. interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. executor – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. lazy version of the array. lazy array (square brackets initiate data reading)

### arrays¶

TTreeMethods.arrays(branches=None, outputtype=<type 'dict'>, namedecode=None, entrystart=None, entrystop=None, flatten=False, cache=None, basketcache=None, keycache=None, executor=None, blocking=True)

Read many branches into arrays (or other objects if provided alternate interpretations).

Parameters: branches – if None (default), select all interpretable branches; if a function TBranchMethods ⇒ None or Interpretation, select branches for which the function does not return None and use the interpretation it returns otherwise; if a dict of str → Interpretation, select branches named by keys and use interpretations from the associated values; if a list of str, select branches by name; if a single str, select a single branch. The selection by string can include filename-like glob characters (*, ?, [...]) or it can be a full regular expression (Python flavored) if surrounded by slashes, like /pattern/i (where i is an optional Python re flag). outputtype (type) – constructor for the desired yield type, such as dict (default), OrderedDict, tuple, namedtuple, custom user class, etc. namedecode (None or str) – if None (default) return names as uninterpreted byte strings (type bytes in Python 3); if a string like "ascii" or "utf-8", decode bytes to a string using the specified encoding. entrystart (None or int) – entry at which reading starts (inclusive). If None (default), start at the beginning of the branch. entrystop (None or int) – entry at which reading stops (exclusive). If None (default), stop at the end of the branch. flatten (bool) – if True (not default), convert JaggedArrays into flat Numpy arrays. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. executor – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. blocking (bool) – if True (default), do not exit this function until the arrays are read, and return those arrays. If False, exit immediately and return a zero-argument function. That zero-argument function returns the desired array, and it blocks until the array is available. This option is only useful with a non-None executor. branch data. outputtype of arrays or other objects, depending on interpretation

### lazyarrays¶

TTreeMethods.lazyarrays(branches=None, outputtype=<type 'dict'>, namedecode=None, limitbytes=1048576, cache=None, basketcache=None, keycache=None, executor=None)

Create many lazy arrays.

Parameters: branches – if None (default), select all interpretable branches; if a function TBranchMethods ⇒ None or Interpretation, select branches for which the function does not return None and use the interpretation it returns otherwise; if a dict of str → Interpretation, select branches named by keys and use interpretations from the associated values; if a list of str, select branches by name; if a single str, select a single branch. The selection by string can include filename-like glob characters (*, ?, [...]) or it can be a full regular expression (Python flavored) if surrounded by slashes, like /pattern/i (where i is an optional Python re flag). outputtype (type) – constructor for the desired yield type, such as dict (default), OrderedDict, tuple, namedtuple, custom user class, etc. namedecode (None or str) – if None (default) return names as uninterpreted byte strings (type bytes in Python 3); if a string like "ascii" or "utf-8", decode bytes to a string using the specified encoding. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. executor – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. lazy branch data. outputtype of lazy arrays (square brackets initiate data reading)

### iterate¶

TTreeMethods.iterate(branches=None, entrysteps=None, outputtype=<type 'dict'>, namedecode=None, reportentries=False, entrystart=None, entrystop=None, flatten=False, cache=None, basketcache=None, keycache=None, executor=None, blocking=True)

Iterate over many arrays at once, yielding the same number of entries from all selected branches in each step.

Depending on the “entrysteps” parameter, the number of entries in one step may differ from the number of entries in the next step, but in every step, the same number of entries is retrieved from all baskets.

Parameters: branches – if None (default), select all interpretable branches; if a function TBranchMethods ⇒ None or Interpretation, select branches for which the function does not return None and use the interpretation it returns otherwise; if a dict of str → Interpretation, select branches named by keys and use interpretations from the associated values; if a list of str, select branches by name; if a single str, select a single branch. The selection by string can include filename-like glob characters (*, ?, [...]) or it can be a full regular expression (Python flavored) if surrounded by slashes, like /pattern/i (where i is an optional Python re flag). entrysteps (None, positive int, or iterable of (int, int) pairs) – if None (default), iterate in steps of TTree clusters (number of entries for which all branches’ baskets align); if an integer, iterate in steps of equal numbers of entries (except at the end of a file); otherwise, iterate in explicit, user-specified (start, stop) intervals (“start” is inclusive and “stop” is exclusive). outputtype (type) – constructor for the desired yield type, such as dict (default), OrderedDict, tuple, namedtuple, custom user class, etc. namedecode (None or str) – if None (default) return names as uninterpreted byte strings (type bytes in Python 3); if a string like "ascii" or "utf-8", decode bytes to a string using the specified encoding. reportentries (bool) – if False (default), yield only arrays (as outputtype); otherwise, yield 3-tuple: (entry start, entry stop, arrays), where entry start is inclusive and entry stop is exclusive. entrystart (None or int) – entry at which reading starts (inclusive). If None (default), start at the beginning of the branch. entrystop (None or int) – entry at which reading stops (exclusive). If None (default), stop at the end of the branch. flatten (bool) – if True (not default), convert JaggedArrays into flat Numpy arrays. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. executor – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. blocking (bool) – if True (default), do not exit this function until the arrays are read, and return those arrays. If False, exit immediately and return a zero-argument function. That zero-argument function returns the desired array, and it blocks until the array is available. This option is only useful with a non-None executor. aligned array segments from the TTree. iterator over (int, int, outputtype) (if reportentries) or just outputtype (otherwise)

### pandas¶

TTree objects can be converted into Pandas DataFrames.

TTreeMethods.pandas = methods for interacting with Pandas.
TTreeMethods_pandas.df(branches=None, namedecode='utf-8', entrystart=None, entrystop=None, flatten=True, cache=None, basketcache=None, keycache=None, executor=None, blocking=True)

Create a Pandas DataFrame from some branches.

Parameters: branches – if None (default), select all interpretable branches; if a function TBranchMethods ⇒ None or Interpretation, select branches for which the function does not return None and use the interpretation it returns otherwise; if a dict of str → Interpretation, select branches named by keys and use interpretations from the associated values; if a list of str, select branches by name; if a single str, select a single branch. The selection by string can include filename-like glob characters (*, ?, [...]) or it can be a full regular expression (Python flavored) if surrounded by slashes, like /pattern/i (where i is an optional Python re flag). namedecode (None or str) – if "utf-8" (default) or other encoding name, decode column names as strings; if None, return names as uninterpreted byte strings (type bytes in Python 3). entrystart (None or int) – entry at which reading starts (inclusive). If None (default), start at the beginning of the branch. entrystop (None or int) – entry at which reading stops (exclusive). If None (default), stop at the end of the branch. flatten (bool) – if True (default), convert JaggedArrays into flat Numpy arrays and turn the DataFrame index into a two-level MultiIndex to represent the structure. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. executor – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. data frame (see docs). Pandas DataFrame

## uproot.tree.TBranchMethods¶

Every class read from a ROOT file named “TBranch” is mixed in with TBranchMethods so that the following methods are available. Subclasses of “TBranch” (such as “TBranchElement”) inherit the mix-in.

class uproot.tree.TBranchMethods

Adds array reading methods to TBranch objects that have been streamed from a ROOT file.

• square brackets (__getitem__) returns a subbranch by name (see get).
• the len function (__len__) returns the number of entries (same as numentries).
• iteration (__iter__) has no implementation. This is to avoid confusion between iterating over all subbranches (probably not what you want, but fitting the pattern set by ROOTDirectory and dict) and iterating over the data.

Attributes, properties, and methods:

Branch information:

• numentries (int) number of entries in the TBranch (same as len).
• uncompressedbytes the number of bytes contained in the TBranch (data and offsets; not including any key headers) after decompression, if applicable.
• compressedbytes the number of bytes contained in the TBranch (data and offsets; not including any key headers) before decompression, if applicable.
• compressionratio the uncompressed bytes divided by compressed bytes (greater than or equal to 1).
• numitems the number of items in the TBranch, under a given interpretation.

### branch accessors¶

TBranchMethods.get(name, recursive=True, filtername=<function nofilter>, filtertitle=<function nofilter>, aliases=True)

Return a subbranch by name (at any level of depth).

Parameters: name (str) – name of the subbranch to return. branch object. TBranch

Notes

This method can be accessed more directly through square brackets (__getitem__) on the TBranch object.

TBranchMethods.iterkeys(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Iterate over subbranch names.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. subbranch names. iterator over bytes
TBranchMethods.itervalues(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Iterate over subbranches.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. subbranches. iterator over TBranch
TBranchMethods.iteritems(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Iterate over (subbranch name, subbranch) pairs.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. (subbranch name, subbranch) pairs. iterator over (bytes, TBranch)
TBranchMethods.keys(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Return subbranch names.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. subbranch names. list of bytes
TBranchMethods.values(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Return subbranches.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. subbranches. list of TBranch
TBranchMethods.items(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Return (subbranch name, subbranch) pairs.

Parameters: recursive (bool) – if False (default), only iterate at this tree/branch level; if True, depth-first iterate over all subbranches as well. filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. (subbranch name, subbranch) pairs. list of (bytes, TBranch)
TBranchMethods.allkeys(recursive=False, filtername=<function nofilter>, filtertitle=<function nofilter>)

Return subbranch names at all levels of depth (shortcut for passing recursive=True to keys).

Parameters: filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. subbranch names. list of bytes
TBranchMethods.allvalues(filtername=<function nofilter>, filtertitle=<function nofilter>)

Return subbranches at all levels of depth (shortcut for passing recursive=True to values).

Parameters: filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. subbranches. list of TBranch
TBranchMethods.allitems(filtername=<function nofilter>, filtertitle=<function nofilter>)

Return (subbranch name, subbranch) pairs at all levels of depth (shortcut for passing recursive=True to items).

Parameters: filtername (function: str ⇒ bool) – only branches for which filtername(name) returns True are returned. Default returns True for all input. filtertitle (function: str ⇒ bool) – only branches for which filtertitle(title) returns True are returned. Default returns True for all input. (subbranch name, subbranch)* pairs. list of (bytes, TBranch

### branch information¶

TBranchMethods.uncompressedbytes(keycache=None)

The number of bytes contained in the TBranch (data and offsets; not including any key headers) after decompression, if applicable.

Parameters: keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. uncompressed bytes. int
TBranchMethods.compressedbytes(keycache=None)

The number of bytes contained in the TBranch (data and offsets; not including any key headers) before decompression, if applicable.

Parameters: keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. compressed bytes. int
TBranchMethods.compressionratio(keycache=None)

The uncompressed bytes divided by compressed bytes (greater than or equal to 1).

Parameters: keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. compression ratio. float
TBranchMethods.numitems(interpretation=None, keycache=None)

The number of items in the TBranch, under a given interpretation.

Parameters: interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. number of items. int

TBranchMethods.basket_entrystart(i)

The starting entry for a given basket (inclusive).

Parameters: i (non-negative int) – basket number (must be greater than or equal to zero and strictly less than numbaskets). starting entry. int
TBranchMethods.basket_entrystop(i)

The stopping entry for a given basket (exclusive).

Parameters: i (non-negative int) – basket number (must be greater than or equal to zero and strictly less than numbaskets). stopping entry. int
TBranchMethods.basket_numentries(i)

The number of entries in a given basket.

Parameters: i (non-negative int) – basket number (must be greater than or equal to zero and strictly less than numbaskets). number of entries. int
TBranchMethods.basket_uncompressedbytes(i, keycache=None)

The number of bytes contained in the basket (data and offsets; not including any key headers) after decompression, if applicable.

Parameters: i (non-negative int) – basket number (must be greater than or equal to zero and strictly less than numbaskets). keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. number of uncompressed bytes. int
TBranchMethods.basket_compressedbytes(i)

The number of bytes contained in the basket (data and offsets; not including any key headers) before decompression, if applicable.

Parameters: i (non-negative int) – basket number (must be greater than or equal to zero and strictly less than numbaskets). keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. number of compressed bytes. int
TBranchMethods.basket_numitems(i, interpretation=None, keycache=None)

The number of items in the basket, under a given interpretation.

Parameters: i (non-negative int) – basket number (must be greater than or equal to zero and strictly less than numbaskets). interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. number of items. int

### array¶

TBranchMethods.array(interpretation=None, entrystart=None, entrystop=None, flatten=False, cache=None, basketcache=None, keycache=None, executor=None, blocking=True)

Read the branch into an array (or other object if provided an alternate interpretation).

Parameters: interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. entrystart (None or int) – entry at which reading starts (inclusive). If None (default), start at the beginning of the branch. entrystop (None or int) – entry at which reading stops (exclusive). If None (default), stop at the end of the branch. flatten (bool) – if True (not default), convert JaggedArrays into flat Numpy arrays. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. executor – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. blocking (bool) – if True (default), do not exit this function until the arrays are read, and return those arrays. If False, exit immediately and return a zero-argument function. That zero-argument function returns the desired array, and it blocks until the array is available. This option is only useful with a non-None executor. branch data. array or other object, depending on interpretation

### lazyarray¶

TBranchMethods.lazyarray(interpretation=None, limitbytes=1048576, cache=None, basketcache=None, keycache=None, executor=None)

Create a lazy array that would read the branch as needed.

Parameters: interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. executor – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. lazy version of branch data. lazy array (square brackets initiate data reading)

TBranchMethods.basket(i, interpretation=None, entrystart=None, entrystop=None, flatten=False, cache=None, basketcache=None, keycache=None)

Parameters: i (non-negative int) – basket number (must be greater than or equal to zero and strictly less than numbaskets). interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. entrystart (None or int) – entry at which reading starts (inclusive). If None (default), start at the beginning of the branch. entrystop (None or int) – entry at which reading stops (exclusive). If None (default), stop at the end of the branch. flatten (bool) – if True (not default), convert JaggedArrays into flat Numpy arrays. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. basket data. array or other object, depending on interpretation

TBranchMethods.baskets(interpretation=None, entrystart=None, entrystop=None, flatten=False, cache=None, basketcache=None, keycache=None, reportentries=False, executor=None, blocking=True)

Parameters: interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. entrystart (None or int) – entry at which reading starts (inclusive). If None (default), start at the beginning of the branch. entrystop (None or int) – entry at which reading stops (exclusive). If None (default), stop at the end of the branch. flatten (bool) – if True (not default), convert JaggedArrays into flat Numpy arrays. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. reportentries (bool) – if False (default), yield only arrays (as outputtype); otherwise, yield 3-tuple: (entry start, entry stop, arrays), where entry start is inclusive and entry stop is exclusive. executor – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe. blocking (bool) – if True (default), do not exit this function until the arrays are read, and return those arrays. If False, exit immediately and return a zero-argument function. That zero-argument function returns the desired array, and it blocks until the array is available. This option is only useful with a non-None executor. basket data. list of arrays or other objects, depending on interpretation
TBranchMethods.iterate_baskets(interpretation=None, entrystart=None, entrystop=None, flatten=False, cache=None, basketcache=None, keycache=None, reportentries=False)
Parameters: interpretation (None or Interpretation) – the meaning imposed upon the bytes of the file and the ultimate form to instantiate. If None (default), interpret will be applied to the branch to generate an interpretation. entrystart (None or int) – entry at which reading starts (inclusive). If None (default), start at the beginning of the branch. entrystop (None or int) – entry at which reading stops (exclusive). If None (default), stop at the end of the branch. flatten (bool) – if True (not default), convert JaggedArrays into flat Numpy arrays. cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss. basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache. keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access. reportentries (bool) – if False (default), yield only arrays (as outputtype); otherwise, yield 3-tuple: (entry start, entry stop, arrays), where entry start is inclusive and entry stop is exclusive. basket data. iterator over arrays or other objects, depending on interpretation