uproot.iterate

Defined in uproot.behaviors.RNTuple on line 28.

uproot.behaviors.RNTuple.iterate(files, 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(), step_size='100 MB', decompression_executor=None, library='ak', ak_add_doc=False, how=None, report=False, allow_missing=False, filter_branch=uproot._util.unset, interpretation_executor=uproot._util.unset, custom_classes=uproot._util.unset, **options)
Parameters:

  • files – See below.

  • 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 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_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.)

  • 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, a uproot.TrivialExecutor is created. (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=()).

  • 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.

  • allow_missing (bool) – If True, skip over any files that do not contain the specified RNTuple.

  • 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_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.

  • custom_classes (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.

  • options – See below.

Iterates through contiguous chunks of entries from a set of files.

For example:

>>> for array in uproot.iterate("files*.root:ntuple", filter_names=["x", "y"], step_size=100):
...     # each of the following have 100 entries
...     array["x"], array["y"]

Allowed types for the files parameter:

  • str/bytes: relative or absolute filesystem path or URL, without any colons other than Windows drive letter or URL schema. Examples: "rel/file.root", "C:\abs\file.root", "http://where/what.root"

  • str/bytes: same with an object-within-ROOT path, separated by a colon. Example: "rel/file.root:tdirectory/rntuple"

  • pathlib.Path: always interpreted as a filesystem path or URL only (no object-within-ROOT path), regardless of whether there are any colons. Examples: Path("rel:/file.root"), Path("/abs/path:stuff.root")

  • glob syntax in str/bytes and pathlib.Path. Examples: Path("rel/*.root"), "/abs/*.root:tdirectory/rntuple"

  • dict: keys are filesystem paths, values are objects-within-ROOT paths. Example: {{"/data_v1/*.root": "rntuple_v1", "/data_v2/*.root": "rntuple_v2"}}

  • already-open RNTuple objects.

  • iterables of the above.

Options (type; default): (Not implemented yet.)

  • handler (uproot.source.chunk.Source class; None)

  • timeout (float for HTTP, int for XRootD; 30)

  • max_num_elements (None or int; None)

  • num_workers (int; 1)

  • use_threads (bool; False on the emscripten platform (i.e. in a web browser), else True)

  • num_fallback_workers (int; 10)

  • begin_chunk_size (memory_size; 403, the smallest a ROOT file can be)

  • minimal_ttree_metadata (bool; True)

See also iterate to iterate within a single file.

Other file entry points:

  • uproot.open: opens one file to read any of its objects.

  • uproot.iterate (this function): iterates through chunks of contiguous entries in RNTuples.

  • uproot.concatenate: returns a single concatenated array from RNTuples.

  • uproot.dask: returns an unevaluated Dask array from RNTuples.