uproot.TTree

Defined in uproot.behaviors.TTree on line 12.

Inheritance order:

  1. uproot.behaviors.TBranch.HasBranches

  2. collections.abc.Mapping

  3. collections.abc.Collection

  4. collections.abc.Sized

  5. collections.abc.Iterable

  6. collections.abc.Container
class uproot.behaviors.TTree.TTree

Behaviors for a TTree, which mostly consist of array-reading methods.

Since a uproot.TTree is a uproot.behaviors.TBranch.HasBranches, it is also a Python Mapping, which uses square bracket syntax to extract subbranches:

my_tree["branch"]
my_tree["branch"]["subbranch"]
my_tree["branch/subbranch"]
my_tree["branch/subbranch/subsubbranch"]

name

TTree.name

Name of the TTree.

title

TTree.title

Title of the TTree.

object_path

TTree.object_path

Object path of the TTree.

cache_key

TTree.cache_key

String that uniquely specifies this TTree in its path, to use as part of object and array cache keys.

num_entries

TTree.num_entries

The number of entries in the TTree, as reported by fEntries.

In principle, this could disagree with the num_entries, which is from the TBranch’s fEntries. See that method’s documentation for yet more ways the number of entries could, in principle, be inconsistent.

tree

TTree.tree

Returns self because this is a TTree.

compressed_bytes

TTree.compressed_bytes

The number of compressed bytes in all TBaskets of all TBranches of this TTree, including all the TKey headers (which are always uncompressed).

This information is specified in the TTree metadata (fZipBytes) and can be determined without reading any additional data.

uncompressed_bytes

TTree.uncompressed_bytes

The number of uncompressed bytes in all TBaskets of all TBranches of this TTree, including all the TKey headers.

This information is specified in the TTree metadata (fTotBytes) and can be determined without reading any additional data.

compression_ratio

TTree.compression_ratio

The number of uncompressed bytes divided by the number of compressed bytes for this TTree.

See compressed_bytes and uncompressed_bytes.

aliases

TTree.aliases

The TTree’s fAliases, which are used as the aliases argument to arrays, iterate, uproot.iterate, and uproot.concatenate if one is not given.

The return type is always a dict of str → str, even if there are no aliases (an empty dict).

chunk

TTree.chunk

The uproot.source.chunk.Chunk from which this TTree was read (as a strong, not weak, reference).

The reason the chunk is retained is to read embedded_baskets only if necessary (if the file was opened with options["minimal_ttree_metadata"]=True, the reading of these TBaskets is deferred until they are accessed).

Holding a strong reference to a chunk holds a strong reference to its uproot.source.chunk.Source, preventing open file handles from going out of scope, but so does the uproot.ReadOnlyFile that TTree needs to read data on demand.

postprocess

TTree.postprocess(chunk, cursor, context, file)

branches

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.branches

The list of uproot.TBranch directly under this uproot.TTree or uproot.TBranch (i.e. not recursive).

show

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.show(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True, full_paths=True, name_width=20, typename_width=24, interpretation_width=30, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, recursively descend into the branches’ branches.

  • full_paths (bool) – If True, include the full path to each subbranch with slashes (/); otherwise, use the descendant’s name as the display name.

  • name_width (int) – Number of characters to reserve for the TBranch names.

  • typename_width (int) – Number of characters to reserve for the C++ typenames.

  • interpretation_width (int) – Number of characters to reserve for the uproot.interpretation.Interpretation displays.

  • stream (object with a write(str) method) – Stream to write the output to.

Interactively display the TBranches.

For example,

name                 | typename             | interpretation
---------------------+----------------------+-----------------------------------
event_number         | int32_t              | AsDtype('>i4')
trigger_isomu24      | bool                 | AsDtype('bool')
eventweight          | float                | AsDtype('>f4')
MET                  | TVector2             | AsStridedObjects(Model_TVector2_v3
jetp4                | std::vector<TLorentz | AsJagged(AsStridedObjects(Model_TL
jetbtag              | std::vector<float>   | AsJagged(AsDtype('>f4'), header_by
jetid                | std::vector<bool>    | AsJagged(AsDtype('bool'), header_b

arrays

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.arrays(expressions=None, cut=None, *, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, aliases=None, language=uproot.language.python.PythonLanguage(), entry_start=None, entry_stop=None, decompression_executor=None, interpretation_executor=None, array_cache='inherit', library='ak', ak_add_doc=False, how=None)
Parameters:

  • expressions (None, str, or list of str) – Names of TBranches or aliases to convert to arrays or mathematical expressions of them. Uses the language to evaluate. If None, all TBranches selected by the filters are included.

  • cut (None or str) – If not None, this expression filters all of the expressions.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. If the function returns False or None, the TBranch is excluded; if the function returns True, it is included with its standard interpretation; if an uproot.interpretation.Interpretation, this interpretation overrules the standard one.

  • aliases (None or dict of str → str) – Mathematical expressions that can be used in expressions or other aliases (without cycles). Uses the language engine to evaluate. If None, only the aliases are available.

  • language (uproot.language.Language) – Language used to interpret the expressions and aliases.

  • entry_start (None or int) – The first entry to include. If None, start at zero. If negative, count from the end, like a Python slice.

  • entry_stop (None or int) – The first entry to exclude (i.e. one greater than the last entry to include). If None, stop at num_entries. If negative, count from the end, like a Python slice.

  • decompression_executor (None or Executor with a submit method) – The executor that is used to decompress TBaskets; if None, the file’s decompression_executor is used.

  • interpretation_executor (None or Executor with a submit method) – The executor that is used to interpret uncompressed TBasket data as arrays; if None, the file’s interpretation_executor is used.

  • array_cache ("inherit", None, MutableMapping, or memory size) – Cache of arrays; if “inherit”, use the file’s cache; if None, do not use a cache; if a memory size, create a new cache of this size.

  • library (str or uproot.interpretation.library.Library) – The library that is used to represent arrays. Options are "np" for NumPy, "ak" for Awkward Array, and "pd" for Pandas.

  • ak_add_doc (bool) – If True and library="ak", add the TBranch title to the Awkward __doc__ parameter of the array.

  • how (None, str, or container type) – Library-dependent instructions for grouping. The only recognized container types are tuple, list, and dict. Note that the container type itself must be passed as how, not an instance of that type (i.e. how=tuple, not how=()).

Returns a group of arrays from the TTree.

For example:

>>> my_tree["x"].array()
<Array [-41.2, 35.1, 35.1, ... 32.4, 32.5] type='2304 * float64'>
>>> my_tree["y"].array()
<Array [17.4, -16.6, -16.6, ... 1.2, 1.2, 1.2] type='2304 * float64'>

See also array to read a single TBranch as an array.

See also iterate to iterate over the array in contiguous ranges of entries.

iterate

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.iterate(expressions=None, cut=None, *, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, aliases=None, language=uproot.language.python.PythonLanguage(), entry_start=None, entry_stop=None, step_size='100 MB', decompression_executor=None, interpretation_executor=None, library='ak', ak_add_doc=False, how=None, report=False)
Parameters:

  • expressions (None, str, or list of str) – Names of TBranches or aliases to convert to arrays or mathematical expressions of them. Uses the language to evaluate. If None, all TBranches selected by the filters are included.

  • cut (None or str) – If not None, this expression filters all of the expressions.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. If the function returns False or None, the TBranch is excluded; if the function returns True, it is included with its standard interpretation; if an uproot.interpretation.Interpretation, this interpretation overrules the standard one.

  • aliases (None or dict of str → str) – Mathematical expressions that can be used in expressions or other aliases (without cycles). Uses the language engine to evaluate. If None, only the aliases are available.

  • language (uproot.language.Language) – Language used to interpret the expressions and aliases.

  • entry_start (None or int) – The first entry to include. If None, start at zero. If negative, count from the end, like a Python slice.

  • entry_stop (None or int) – The first entry to exclude (i.e. one greater than the last entry to include). If None, stop at num_entries. If negative, count from the end, like a Python slice.

  • step_size (int or str) – If an integer, the maximum number of entries to include in each iteration step; if a string, the maximum memory size to include. The string must be a number followed by a memory unit, such as “100 MB”.

  • decompression_executor (None or Executor with a submit method) – The executor that is used to decompress TBaskets; if None, the file’s decompression_executor is used.

  • interpretation_executor (None or Executor with a submit method) – The executor that is used to interpret uncompressed TBasket data as arrays; if None, the file’s interpretation_executor is used.

  • library (str or uproot.interpretation.library.Library) – The library that is used to represent arrays. Options are "np" for NumPy, "ak" for Awkward Array, and "pd" for Pandas.

  • ak_add_doc (bool) – If True and library="ak", add the TBranch title to the Awkward __doc__ parameter of the array.

  • how (None, str, or container type) – Library-dependent instructions for grouping. The only recognized container types are tuple, list, and dict. Note that the container type itself must be passed as how, not an instance of that type (i.e. how=tuple, not how=()).

  • report (bool) – If True, this generator yields (arrays, uproot.behaviors.TBranch.Report) pairs; if False, it only yields arrays. The report has data about the TFile, TTree, and global and local entry ranges.

Iterates through contiguous chunks of entries from the TTree.

For example:

>>> for array in tree.iterate(["x", "y"], step_size=100):
...     # each of the following have 100 entries
...     array["x"], array["y"]

See also arrays to read everything in a single step, without iteration.

See also uproot.iterate to iterate over many files.

keys

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.keys(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True, full_paths=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only return the names of branches directly accessible under this object.

  • full_paths (bool) – If True, include the full path to each subbranch with slashes (/); otherwise, use the descendant’s name as the output name.

Returns the names of the subbranches as a list of strings.

values

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.values(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only return branches that are directly accessible under this object.

Returns the subbranches as a list of uproot.TBranch.

(Note: with recursive=False, this is the same as branches.)

items

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.items(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True, full_paths=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only return (name, branch) pairs for branches directly accessible under this object.

  • full_paths (bool) – If True, include the full path to each subbranch with slashes (/) in the name; otherwise, use the descendant’s name as the name without modification.

Returns (name, branch) pairs of the subbranches as a list of 2-tuples of (str, uproot.TBranch).

typenames

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.typenames(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True, full_paths=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only return (name, typename) pairs for branches directly accessible under this object.

  • full_paths (bool) – If True, include the full path to each subbranch with slashes (/) in the name; otherwise, use the descendant’s name as the name without modification.

Returns (name, typename) pairs of the subbranches as a dict of str → str.

iterkeys

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.iterkeys(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True, full_paths=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only return the names of branches directly accessible under this object.

  • full_paths (bool) – If True, include the full path to each subbranch with slashes (/); otherwise, use the descendant’s name as the output name.

Returns the names of the subbranches as an iterator over strings.

itervalues

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.itervalues(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only return branches that are directly accessible under this object.

Returns the subbranches as an iterator over uproot.TBranch.

(Note: with recursive=False, this is the same as branches.)

iteritems

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.iteritems(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True, full_paths=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only return (name, branch) pairs for branches directly accessible under this object.

  • full_paths (bool) – If True, include the full path to each subbranch with slashes (/) in the name; otherwise, use the descendant’s name as the name without modification.

Returns (name, branch) pairs of the subbranches as an iterator over 2-tuples of (str, uproot.TBranch).

itertypenames

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.itertypenames(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True, full_paths=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only return (name, typename) pairs for branches directly accessible under this object.

  • full_paths (bool) – If True, include the full path to each subbranch with slashes (/) in the name; otherwise, use the descendant’s name as the name without modification.

Returns (name, typename) pairs of the subbranches as an iterator over 2-tuples of (str, str).

num_entries_for

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.num_entries_for(memory_size, expressions=None, cut=None, *, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, aliases=None, language=uproot.language.python.PythonLanguage(), entry_start=None, entry_stop=None)
Parameters:

  • memory_size (int or str) – An integer is interpreted as a number of bytes and a string must be a number followed by a unit, such as “100 MB”.

  • expressions (None, str, or list of str) – Names of TBranches or aliases to convert to arrays or mathematical expressions of them. Uses the language to evaluate. If None, all TBranches selected by the filters are included.

  • cut (None or str) – If not None, this expression filters all of the expressions.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • aliases (None or dict of str → str) – Mathematical expressions that can be used in expressions or other aliases (without cycles). Uses the language engine to evaluate. If None, only the aliases are available.

  • language (uproot.language.Language) – Language used to interpret the expressions and aliases.

  • entry_start (None or int) – The first entry to include. If None, start at zero. If negative, count from the end, like a Python slice.

  • entry_stop (None or int) – The first entry to exclude (i.e. one greater than the last entry to include). If None, stop at num_entries. If negative, count from the end, like a Python slice.

Returns an approximate step size as a number of entries to read a given memory_size in each step.

This method does not actually read the TBranch data or compute any expressions to arrive at its estimate. It only uses metadata from the already-loaded TTree; it only needs language to parse the expressions, not to evaluate them.

In addition, the estimate is based on compressed TBasket sizes (the amount of data that would have to be read), not uncompressed TBasket sizes (the amount of data that the final arrays would use in memory, without considering cuts).

This is the algorithm that iterate uses to convert a step_size expressed in memory units into a number of entries.

common_entry_offsets

Inherited from uproot.behaviors.TBranch.HasBranches.

TTree.common_entry_offsets(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True)
Parameters:

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. The TBranch is included if the function returns True, excluded if it returns False.

  • recursive (bool) – If True, descend into any nested subbranches. If False, only consider branches directly accessible under this object. (Only applies when branches=None.)

Returns entry offsets in which TBasket boundaries align in the specified set of branches.

If this uproot.TBranch has no subbranches, the output is identical to entry_offsets.