uproot.concatenate — Uproot documentation

# uproot.concatenate

Defined in uproot.behaviors.RNTuple on line 196.

uproot.behaviors.RNTuple.concatenate(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(), entry_start=None, entry_stop=None, decompression_executor=None, library='ak', ak_add_doc=False, how=None, 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.)

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

  Returns an array with data from a set of files concatenated into one.

  For example:

      >>> array = uproot.concatenate("files*.root:ntuple", filter_field=["x", "y"])

  Depending on the number of files, the number of selected `RFields`, and the size of your computer’s memory, this function might not have enough memory to run.

  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)

  Other file entry points:

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

  - uproot.iterate: iterates through chunks of contiguous entries in `RNTuples`.

  - uproot.concatenate (this function): returns a single concatenated array from `RNTuples`.

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