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:

  • name (bytes) name of the TTree.
  • title (bytes) title of the TTree.
  • numentries (int) number of entries in the TTree (same as len).
  • pandas connector to Pandas functions
  • get return a branch by name (at any level of depth).
  • iterkeys iterate over branch names.
  • itervalues iterate over branches.
  • iteritems iterate over (branch name, branch) pairs.
  • keys return branch names.
  • values return branches.
  • items return (branch name, branch) pairs.
  • allkeys return branch names at all levels of depth (shortcut for passing recursive=True to keys).
  • allvalues return branches at all levels of depth (shortcut for passing recursive=True to values).
  • allitems return (branch name, branch) pairs at all levels of depth (shortcut for passing recursive=True to items).
  • clusters iterate over (int, int) pairs representing cluster entry starts and stops in this TTree (not implemented).

Methods for reading array data:

  • array read one branch into an array (or other object if provided an alternate interpretation).
  • lazyarray create a lazy array that would read the branch as needed.
  • arrays read many branches into arrays (or other objects if provided alternate interpretations).
  • lazyarrays create many lazy arrays.
  • iterate iterate over many arrays at once, yielding the same number of entries from all selected branches in each step.

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.
Returns:selected branch.
Return type: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.
Returns:

names of branches.

Return type:

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.
Returns:

branches.

Return type:

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.
Returns:

name-branch pairs.

Return type:

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.
Returns:

names of branches.

Return type:

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.
Returns:

branches.

Return type:

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.
Returns:

name-branch pairs.

Return type:

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.
Returns:

names of branches.

Return type:

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.
Returns:

branches.

Return type:

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.
Returns:

name-branch pairs.

Return type:

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.
Return type: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 (None or bool) – if True, convert JaggedArrays into flat Numpy arrays. If False (default), make JaggedArrays lists. If None, remove JaggedArrays.
  • 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.
Returns:

Return type:

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.
Returns:

lazy version of the array.

Return type:

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 TBranchMethodsNone 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 (None or bool) – if True, convert JaggedArrays into flat Numpy arrays. If False (default), make JaggedArrays lists. If None, remove JaggedArrays.
  • 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.
Returns:

branch data.

Return type:

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 TBranchMethodsNone 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.
Returns:

lazy branch data.

Return type:

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 TBranchMethodsNone 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 (None or bool) – if True, convert JaggedArrays into flat Numpy arrays. If False (default), make JaggedArrays lists. If None, remove JaggedArrays.
  • 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.
Returns:

aligned array segments from the TTree.

Return type:

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 TBranchMethodsNone 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 (None or bool) – if True (default), convert JaggedArrays into flat Numpy arrays and turn the DataFrame index into a two-level MultiIndex to represent the structure. If False, make JaggedArrays into lists. If None, remove JaggedArrays.
  • 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.
Returns:

data frame (see docs).

Return type:

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:

  • name (bytes) name of the TBranch.
  • title (bytes) title of the TBranch.
  • compression (Compression) the compression algorithm and level specified in the TBranch header. (Actual compression used may differ.)
  • get return a subbranch by name (at any level of depth).
  • iterkeys iterate over subbranch names.
  • itervalues iterate over subbranches.
  • iteritems iterate over (subbranch name, subbranch) pairs.
  • keys return subbranch names.
  • values return subbranches.
  • items return (subbranch name, subbranch) pairs.
  • allkeys return subbranch names at all levels of depth (shortcut for passing recursive=True to keys).
  • allvalues return subbranches at all levels of depth (shortcut for passing recursive=True to values).
  • allitems return (subbranch name, subbranch) pairs at all levels of depth (shortcut for passing recursive=True to items).

Branch information:

  • numentries (int) number of entries in the TBranch (same as len).
  • numbaskets (int) number of baskets in the TBranch.
  • 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.

Basket information:

  • basket_entrystart the starting entry for a given basket (inclusive).
  • basket_entrystop the stopping entry for a given basket (exclusive).
  • basket_numentries the number of entries in a given basket.
  • basket_uncompressedbytes the number of bytes contained in the basket (data and offsets; not including any key headers) after decompression, if applicable.
  • basket_compressedbytes the number of bytes contained in the basket (data and offsets; not including any key headers) before decompression, if applicable.
  • basket_numitems the number of items in the basket, under a given interpretation.

Methods for reading array data:

  • array read the branch into an array (or other object if provided an alternate interpretation).
  • lazyarray create a lazy array that would read the branch as needed.
  • basket read a single basket into an array.
  • baskets read baskets into a list of arrays.
  • iterate_baskets iterate over baskets.

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.
Returns:branch object.
Return type: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.
Returns:

subbranch names.

Return type:

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.
Returns:

subbranches.

Return type:

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.
Returns:

(subbranch name, subbranch) pairs.

Return type:

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.
Returns:

subbranch names.

Return type:

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.
Returns:

subbranches.

Return type:

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.
Returns:

(subbranch name, subbranch) pairs.

Return type:

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.
Returns:

subbranch names.

Return type:

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.
Returns:

subbranches.

Return type:

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.
Returns:

(subbranch name, subbranch)* pairs.

Return type:

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.
Returns:uncompressed bytes.
Return type: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.
Returns:compressed bytes.
Return type: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.
Returns:compression ratio.
Return type: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.
Returns:

number of items.

Return type:

int

basket information

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).
Returns:starting entry.
Return type: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).
Returns:stopping entry.
Return type: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).
Returns:number of entries.
Return type: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.
Returns:

number of uncompressed bytes.

Return type:

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.
Returns:

number of compressed bytes.

Return type:

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.
Returns:

number of items.

Return type:

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 (None or bool) – if True, convert JaggedArrays into flat Numpy arrays. If False (default), make JaggedArrays lists. If None, remove JaggedArrays.
  • 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.
Returns:

branch data.

Return type:

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.
Returns:

lazy version of branch data.

Return type:

lazy array (square brackets initiate data reading)

basket

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

Read a single basket into an array.

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 (None or bool) – if True, convert JaggedArrays into flat Numpy arrays. If False (default), make JaggedArrays lists. If None, remove JaggedArrays.
  • 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.
Returns:

basket data.

Return type:

array or other object, depending on interpretation

baskets

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

Read baskets into a list of arrays.

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 (None or bool) – if True, convert JaggedArrays into flat Numpy arrays. If False (default), make JaggedArrays lists. If None, remove JaggedArrays.
  • 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.
Returns:

basket data.

Return type:

list of arrays or other objects, depending on interpretation

iterate_baskets

TBranchMethods.iterate_baskets(interpretation=None, entrystart=None, entrystop=None, flatten=False, cache=None, basketcache=None, keycache=None, reportentries=False)

Iterate over baskets.

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 (None or bool) – if True, convert JaggedArrays into flat Numpy arrays. If False (default), make JaggedArrays lists. If None, remove JaggedArrays.
  • 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.
Returns:

basket data.

Return type:

iterator over arrays or other objects, depending on interpretation