# uproot.iterate

Defined in uproot.behaviors.TBranch on line 50.

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

    - files – See below.

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

    - 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, a uproot.TrivialExecutor is created.

    - interpretation_executor (None or Executor with a `submit` method) – The executor that is used to interpret uncompressed `TBasket` data as arrays; if None, a uproot.TrivialExecutor is created.

    - 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 | dict) – If True and `library="ak"`, add the TBranch `title` to the Awkward `__doc__` parameter of the array. if dict = {key:value} and `library="ak"`, add the TBranch `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.

    - custom_classes (None or dict) – If a dict, override the classes from the uproot.ReadOnlyFile or `uproot.classes`.

    - allow_missing (bool) – If True, skip over any files that do not contain the specified `TTree`.

    - options – See below.

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

  For example:

      >>> for array in uproot.iterate("files*.root:tree", ["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/ttree"`

  - 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/ttree"`

  - dict: keys are filesystem paths, values are objects-within-ROOT paths. Example: `{{"/data_v1/*.root": "ttree_v1", "/data_v2/*.root": "ttree_v2"}}`

  - already-open TTree objects.

  - iterables of the above.

  Options (type; default):

  - 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 `TTrees`.

  - uproot.concatenate: returns a single concatenated array from `TTrees`.

  - uproot.dask: returns an unevaluated Dask array from `TTrees`.