uproot.behaviors.RNTuple.HasFields

Defined in uproot.behaviors.RNTuple on line 403.

Inheritance order:
`collections.abc.Mapping` `collections.abc.Collection` `collections.abc.Sized` `collections.abc.Iterable` `collections.abc.Container`

class uproot.behaviors.RNTuple.HasFields

Abstract class of behaviors for anything that “has fields,” namely uproot.models.RNTuple.RNTuple and uproot.models.RNTuple.RField, which mostly consist of array-reading methods.

A uproot.behaviors.RNTuple.HasFields is a Python Mapping, which uses square bracket syntax to extract subfields:

my_rntuple["field"]
my_rntuple["field"]["subfield"]
my_rntuple["field.subfield"]
my_rntuple["field.subfield.subsubfield"]
my_rntuple["field/subfield/subsubfield"]
my_rntuple["field\subfield\subsubfield"]

ntuple

HasFields.ntuple: The uproot.models.RNTuple.RNTuple that this uproot.models.RNTuple.HasFields is part of.

num_entries

HasFields.num_entries: The number of entries in the RNTuple.

fields

HasFields.fields: The list of uproot.models.RNTuple.RField directly under this uproot.models.RNTuple.RNTuple or uproot.models.RNTuple.RField (i.e. not recursive).

path

HasFields.path: The full path of the field in the uproot.models.RNTuple.RNTuple. When it is the RNTuple itself, this is ".".

to_akform

HasFields.to_akform(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

Returns the an Awkward Form with the structure of the data in the RNTuple or RField.

arrays

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

Parameters:

expressions (None, str, or list of str) – Names of RFields or aliases to convert to arrays or mathematical expressions of them. Uses the language to evaluate. If None, all RFields selected by the filters are included. (Not implemented yet.)
cut (None or str) – If not None, this expression filters all of the expressions. (Not implemented yet.)
filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select RFields 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 RFields by type.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. If the function returns False or None, the RField is excluded; if the function returns True, it is included.
aliases (None or dict of str → str) – Mathematical expressions that can be used in expressions or other aliases. Uses the language engine to evaluate. (Not implemented yet.)
language (uproot.language.Language) – Language used to interpret the expressions and aliases. (Not implemented yet.)
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 RPages; if None, the file’s decompression_executor is used. (Not implemented yet.)
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. (Not implemented yet.)
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. (Not implemented yet.)
ak_add_doc (bool | dict) – If True and library="ak", add the RField name to the Awkward __doc__ parameter of the array. if dict = {key:value} and library="ak", add the RField value to the Awkward key 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=()).
interpretation_executor (None) – This argument is not used and is only included for now for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.
filter_branch – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

Returns a group of arrays from the RNTuple.

For example:

>>> my_ntuple.arrays()
<Array [{my_vector: [1, 2]}, {...}] type='2 * {my_vector: var * int64}'>

See also uproot.behaviors.RNTuple.HasFields.array to read a single RField as an array.

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

iterate

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

Parameters:

expressions (None, str, or list of str) – Names of RFields or aliases to convert to arrays or mathematical expressions of them. Uses the language to evaluate. If None, all RFields selected by the filters are included. (Not implemented yet.)
cut (None or str) – If not None, this expression filters all of the expressions. (Not implemented yet.)
filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select RFields 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 EFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool, or None) – A filter to select RFields using the full uproot.models.RNTuple.RField object. If the function returns False or None, the RField is excluded; if the function returns True, it is included.
aliases (None or dict of str → str) – Mathematical expressions that can be used in expressions or other aliases. Uses the language engine to evaluate. (Not implemented yet.)
language (uproot.language.Language) – Language used to interpret the expressions and aliases. (Not implemented yet.)
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 RPages; if None, the file’s decompression_executor is used. (Not implemented yet.)
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. (Not implemented yet.)
ak_add_doc (bool | dict) – If True and library="ak", add the RField name to the Awkward __doc__ parameter of the array. if dict = {key:value} and library="ak", add the RField value to the Awkward key parameter of the array. (Not implemented yet.)
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, RNTuple, and global and local entry ranges. (Not implemented yet.)
interpretation_executor (None) – This argument is not used and is only included for now for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

Iterates through contiguous chunks of entries from the RNTuple.

For example:

>>> for array in rntuple.iterate(filter_name=["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

HasFields.keys(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, full_paths=True, ignore_duplicates=False, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, descend into any nested subfields. If False, only return the names of the top fields.
full_paths (bool) – If True, include the full path to each subfield with periods (.); otherwise, use the descendant’s name as the output name.
ignore_duplicates (bool) – If True, return a set of the keys; otherwise, return the full list of keys.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

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

values

HasFields.values(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, descend into any nested subfields. If False, only return the names of the top fields.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

Returns the subfields as a list of uproot.behaviors.RField.RField.

(Note: with recursive=False, this is the same as uproot.behaviors.TBranch.HasFields.fields.)

items

HasFields.items(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, full_paths=True, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, descend into any nested subfields. If False, only return the names of the top fields.
full_paths (bool) – If True, include the full path to each subfield with periods (.); otherwise, use the descendant’s name as the output name.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

Returns (name, field) pairs of the subfields as a list of 2-tuples of (str, uproot.behaviors.RField.RField).

typenames

HasFields.typenames(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, full_paths=True, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, descend into any nested subfields. If False, only return the names of the top fields.
full_paths (bool) – If True, include the full path to each subfield with periods (.); otherwise, use the descendant’s name as the output name.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

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

iterkeys

HasFields.iterkeys(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, full_paths=True, ignore_duplicates=False, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, descend into any nested subfields. If False, only return the names of the top fields.
full_paths (bool) – If True, include the full path to each subfield with periods (.); otherwise, use the descendant’s name as the output name.
ignore_duplicates (bool) – If True, return a set of the keys; otherwise, return the full list of keys.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

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

itervalues

HasFields.itervalues(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, descend into any nested subfields. If False, only return the names of the top fields.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

Returns the subfields as an iterator over uproot.behaviors.RField.RField.

(Note: with recursive=False, this is the same as uproot.behaviors.RField.HasFields.fields.)

iteritems

HasFields.iteritems(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, full_paths=True, ignore_duplicates=False, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, descend into any nested subfields. If False, only return the names of the top fields.
full_paths (bool) – If True, include the full path to each subfield with periods (.); otherwise, use the descendant’s name as the output name.
ignore_duplicates (bool) – If True, return a set of the keys; otherwise, return the full list of keys.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

Returns (name, field) pairs of the subfields as an iterator over 2-tuples of (str, uproot.behaviors.RField.RField).

itertypenames

HasFields.itertypenames(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, full_paths=True, filter_branch=uproot._util.unset)

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 ``RFields``s 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, descend into any nested subfields. If False, only return the names of the top fields.
full_paths (bool) – If True, include the full path to each subfield with periods (.); otherwise, use the descendant’s name as the output name.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

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

num_entries_for

HasFields.num_entries_for(memory_size, expressions=None, cut=None, *, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, aliases=None, language=uproot.language.python.PythonLanguage(), entry_start=None, entry_stop=None, filter_branch=uproot._util.unset)

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 RFields or aliases to convert to arrays or mathematical expressions of them. Uses the language to evaluate. If None, all RFields selected by the filters are included. (Not implemented yet.)
cut (None or str) – If not None, this expression filters all of the expressions. (Not implemented yet.)
filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select RFields 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 RFields by type.
filter_field (None or function of uproot.models.RField.RField → bool, or None) – A filter to select RFields using the full uproot.models.RField.RField object. The RField 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. Uses the language engine to evaluate.
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.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

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 RField data or compute any expressions to arrive at its estimate. It only uses metadata from the already-loaded RNTuple; it only needs language to parse the expressions, not to evaluate them.

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

show

HasFields.show(*, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_field=<function no_filter>, recursive=True, name_width=20, typename_width=24, path_width=30, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, full_paths=uproot._util.unset, filter_branch=uproot._util.unset, interpretation_width=uproot._util.unset)

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 RFields 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 RFields by type.
filter_field (None or function of uproot.models.RNTuple.RField → bool, or None) – A filter to select RFields using the full uproot.models.RNTuple.RField object. The RField is included if the function returns True, excluded if it returns False.
recursive (bool) – If True, recursively descend into subfields.
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 (None) – Number of characters to reserve for the uproot.interpretation.Interpretation displays.
stream (object with a write(str) method) – Stream to write the output to.
full_paths (None) – This argument is not used and is only included for now for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.
filter_branch (None or function of uproot.models.RNTuple.RField → bool) – An alias for filter_field included for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.
interpretation_width – This argument is not used and is only included for now for compatibility with software that was used for uproot.TBranch. This argument should not be used and will be removed in a future version.

Interactively display the RFields.

For example,

>>> my_ntuple.show()
name                 | typename                 | path
---------------------+--------------------------+-------------------------------
my_int               | std::int64_t             | my_int
my_vec               | std::vector<std::int6... | my_vec
_0                   | std::int64_t             | my_vec._0

source

HasFields.source

Returns the associated source of data for this container, if it exists

Returns: uproot.source.chunk.Source or None